1 | #------------------------------------------------------------------------------
|
---|
2 | # File: ExifTool.pod - Documentation for File::ExifTool
|
---|
3 | #
|
---|
4 | # Description: Read and write meta information
|
---|
5 | #
|
---|
6 | # URL: http://owl.phy.queensu.ca/~phil/exiftool/
|
---|
7 | #
|
---|
8 | # Legal: Copyright (c) 2003-2010, Phil Harvey (phil at owl.phy.queensu.ca)
|
---|
9 | # This library is free software; you can redistribute it and/or
|
---|
10 | # modify it under the same terms as Perl itself.
|
---|
11 | #------------------------------------------------------------------------------
|
---|
12 |
|
---|
13 | =head1 NAME
|
---|
14 |
|
---|
15 | Image::ExifTool - Read and write meta information
|
---|
16 |
|
---|
17 | =head1 SYNOPSIS
|
---|
18 |
|
---|
19 | use Image::ExifTool qw(:Public);
|
---|
20 |
|
---|
21 | # ---- Simple procedural usage ----
|
---|
22 |
|
---|
23 | # Get hash of meta information tag names/values from an image
|
---|
24 | $info = ImageInfo('a.jpg');
|
---|
25 |
|
---|
26 | # ---- Object-oriented usage ----
|
---|
27 |
|
---|
28 | # Create a new Image::ExifTool object
|
---|
29 | $exifTool = new Image::ExifTool;
|
---|
30 |
|
---|
31 | # Extract meta information from an image
|
---|
32 | $exifTool->ExtractInfo($file, \%options);
|
---|
33 |
|
---|
34 | # Get list of tags in the order they were found in the file
|
---|
35 | @tagList = $exifTool->GetFoundTags('File');
|
---|
36 |
|
---|
37 | # Get the value of a specified tag
|
---|
38 | $value = $exifTool->GetValue($tag, $type);
|
---|
39 |
|
---|
40 | # Get a tag description
|
---|
41 | $description = $exifTool->GetDescription($tag);
|
---|
42 |
|
---|
43 | # Get the group name associated with this tag
|
---|
44 | $group = $exifTool->GetGroup($tag, $family);
|
---|
45 |
|
---|
46 | # Set a new value for a tag
|
---|
47 | $exifTool->SetNewValue($tag, $newValue);
|
---|
48 |
|
---|
49 | # Write new meta information to a file
|
---|
50 | $success = $exifTool->WriteInfo($srcfile, $dstfile);
|
---|
51 |
|
---|
52 | # ...plus a host of other useful methods...
|
---|
53 |
|
---|
54 | =head1 DESCRIPTION
|
---|
55 |
|
---|
56 | ExifTool provides an extensible set of perl modules to read and write meta
|
---|
57 | information in a wide variety of files, including the maker note information
|
---|
58 | of many digital cameras by various manufacturers such as Canon, Casio,
|
---|
59 | FujiFilm, GE, HP, JVC/Victor, Kodak, Leaf, Minolta/Konica-Minolta, Nikon,
|
---|
60 | Olympus/Epson, Panasonic/Leica, Pentax/Asahi, Reconyx, Ricoh, Samsung,
|
---|
61 | Sanyo, Sigma/Foveon and Sony.
|
---|
62 |
|
---|
63 | Below is a list of file types and meta information formats currently
|
---|
64 | supported by ExifTool (r = read, w = write, c = create):
|
---|
65 |
|
---|
66 | File Types
|
---|
67 | ------------+-------------+-------------+-------------+------------
|
---|
68 | 3FR r | DVB r | M4A/V r | PBM r/w | RWL r/w
|
---|
69 | 3G2 r | DYLIB r | MEF r/w | PDF r/w | RWZ r
|
---|
70 | 3GP r | EIP r | MIE r/w/c | PEF r/w | RM r
|
---|
71 | ACR r | EPS r/w | MIFF r | PFA r | SO r
|
---|
72 | AFM r | ERF r/w | MKA r | PFB r | SR2 r/w
|
---|
73 | AI r/w | EXE r | MKS r | PFM r | SRF r
|
---|
74 | AIFF r | EXIF r/w/c | MKV r | PGF r | SRW r/w
|
---|
75 | APE r | F4A/V r | MNG r/w | PGM r/w | SVG r
|
---|
76 | ARW r/w | FLA r | MOS r/w | PICT r | SWF r
|
---|
77 | ASF r | FLAC r | MOV r | PMP r | THM r/w
|
---|
78 | AVI r | FLV r | MP3 r | PNG r/w | TIFF r/w
|
---|
79 | BMP r | FPX r | MP4 r | PPM r/w | TTC r
|
---|
80 | BTF r | GIF r/w | MPC r | PPT r | TTF r
|
---|
81 | COS r | GZ r | MPG r | PPTX r | VRD r/w/c
|
---|
82 | CR2 r/w | HDP r/w | MPO r/w | PS r/w | VSD r
|
---|
83 | CRW r/w | HTML r | MQV r | PSB r/w | WAV r
|
---|
84 | CS1 r/w | ICC r/w/c | MRW r/w | PSD r/w | WDP r/w
|
---|
85 | DCM r | IIQ r/w | MXF r | PSP r | WEBP r
|
---|
86 | DCP r/w | IND r/w | NEF r/w | QTIF r | WEBM r
|
---|
87 | DCR r | ITC r | NRW r/w | RA r | WMA r
|
---|
88 | DFONT r | JNG r/w | NUMBERS r | RAF r/w | WMV r
|
---|
89 | DIVX r | JP2 r/w | ODP r | RAM r | X3F r/w
|
---|
90 | DJVU r | JPEG r/w | ODS r | RAR r | XCF r
|
---|
91 | DLL r | K25 r | ODT r | RAW r/w | XLS r
|
---|
92 | DNG r/w | KDC r | OGG r | RIFF r | XLSX r
|
---|
93 | DOC r | KEY r | ORF r/w | RSRC r | XMP r/w/c
|
---|
94 | DOCX r | LNK r | OTF r | RTF r | ZIP r
|
---|
95 | DV r | M2TS r | PAGES r | RW2 r/w |
|
---|
96 |
|
---|
97 | Meta Information
|
---|
98 | ----------------------+----------------------+---------------------
|
---|
99 | EXIF r/w/c | CIFF r/w | Ricoh RMETA r
|
---|
100 | GPS r/w/c | AFCP r/w | Picture Info r
|
---|
101 | IPTC r/w/c | Kodak Meta r/w | Adobe APP14 r
|
---|
102 | XMP r/w/c | FotoStation r/w | MPF r
|
---|
103 | MakerNotes r/w/c | PhotoMechanic r/w | Stim r
|
---|
104 | Photoshop IRB r/w/c | JPEG 2000 r | APE r
|
---|
105 | ICC Profile r/w/c | DICOM r | Vorbis r
|
---|
106 | MIE r/w/c | Flash r | SPIFF r
|
---|
107 | JFIF r/w/c | FlashPix r | DjVu r
|
---|
108 | Ducky APP12 r/w/c | QuickTime r | M2TS r
|
---|
109 | PDF r/w/c | Matroska r | PE/COFF r
|
---|
110 | PNG r/w/c | GeoTIFF r | AVCHD r
|
---|
111 | Canon VRD r/w/c | PrintIM r | ZIP r
|
---|
112 | Nikon Capture r/w/c | ID3 r | (and more)
|
---|
113 |
|
---|
114 | =head1 CONFIGURATION
|
---|
115 |
|
---|
116 | User-defined tags can be added via the ExifTool configuration file, or by
|
---|
117 | defining the %Image::ExifTool::UserDefined hash before calling any ExifTool
|
---|
118 | methods. See "ExifTool_config" in the ExifTool distribution for more
|
---|
119 | details.
|
---|
120 |
|
---|
121 | By default ExifTool looks for a configuration file named ".ExifTool_config"
|
---|
122 | first in your home directory, then in the directory of the application
|
---|
123 | script, but a different file may be specified by setting the ExifTool
|
---|
124 | C<configFile> variable before using Image::ExifTool. For example:
|
---|
125 |
|
---|
126 | BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
|
---|
127 | use Image::ExifTool;
|
---|
128 |
|
---|
129 | or the configuration feature may be disabled by setting C<configFile> to an
|
---|
130 | empty string:
|
---|
131 |
|
---|
132 | BEGIN { $Image::ExifTool::configFile = '' }
|
---|
133 | use Image::ExifTool;
|
---|
134 |
|
---|
135 | =head1 EXPORTS
|
---|
136 |
|
---|
137 | Exports nothing by default, but L</ImageInfo> and all static methods may be
|
---|
138 | exported with the C<:Public> export list.
|
---|
139 |
|
---|
140 | =head1 METHODS
|
---|
141 |
|
---|
142 | All ExifTool features are accessed through the methods of the public
|
---|
143 | interface listed below. Other Image::ExifTool methods and modules should
|
---|
144 | not be accessed directly because their interface may change with future
|
---|
145 | versions.
|
---|
146 |
|
---|
147 | None of these methods should ever die or issue warnings to STDERR if called
|
---|
148 | with the proper arguments (with the exception of L</SetNewValue> which
|
---|
149 | returns an error string when called in list context, or sends the error to
|
---|
150 | STDERR otherwise). Error and warning messages that occur during processing
|
---|
151 | are stored in the values of the Error and Warning tags, and are accessible
|
---|
152 | via the L</GetValue> method.
|
---|
153 |
|
---|
154 | =head2 new
|
---|
155 |
|
---|
156 | Creates a new ExifTool object.
|
---|
157 |
|
---|
158 | $exifTool = new Image::ExifTool;
|
---|
159 |
|
---|
160 | Note that ExifTool uses AUTOLOAD to load non-member methods, so any class
|
---|
161 | using Image::ExifTool as a base class must define an AUTOLOAD which calls
|
---|
162 | Image::ExifTool::DoAutoLoad(). ie)
|
---|
163 |
|
---|
164 | sub AUTOLOAD
|
---|
165 | {
|
---|
166 | Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
|
---|
167 | }
|
---|
168 |
|
---|
169 | =head2 ImageInfo
|
---|
170 |
|
---|
171 | Read image file and return meta information. This is the one step function
|
---|
172 | for retrieving meta information from an image. Internally, L</ImageInfo>
|
---|
173 | calls L</ExtractInfo> to extract the information, L</GetInfo> to generate
|
---|
174 | the information hash, and L</GetTagList> for the returned tag list.
|
---|
175 |
|
---|
176 | # return meta information for 2 tags only (procedural)
|
---|
177 | $info = ImageInfo($filename, $tag1, $tag2);
|
---|
178 |
|
---|
179 | # return information about an open image file (object-oriented)
|
---|
180 | $info = $exifTool->ImageInfo(\*FILE);
|
---|
181 |
|
---|
182 | # return information from image data in memory for specified tags
|
---|
183 | %options = (PrintConv => 0);
|
---|
184 | @tagList = qw(filename imagesize xmp:creator exif:* -ifd1:*);
|
---|
185 | $info = ImageInfo(\$imageData, \@tagList, \%options);
|
---|
186 |
|
---|
187 | # extract information from an embedded thumbnail image
|
---|
188 | $info = ImageInfo('image.jpg', 'thumbnailimage');
|
---|
189 | $thumbInfo = ImageInfo($$info{ThumbnailImage});
|
---|
190 |
|
---|
191 | =over 4
|
---|
192 |
|
---|
193 | =item Inputs:
|
---|
194 |
|
---|
195 | L</ImageInfo> is very flexible about the input arguments, and interprets
|
---|
196 | them based on their type. It may be called with one or more arguments.
|
---|
197 | The one required argument is either a SCALAR (the image file name), a file
|
---|
198 | reference (a reference to the image file) or a SCALAR reference (a
|
---|
199 | reference to the image in memory). Other arguments are optional. The
|
---|
200 | order of the arguments is not significant, except that the first SCALAR is
|
---|
201 | taken to be the file name unless a file reference or scalar reference comes
|
---|
202 | earlier in the argument list.
|
---|
203 |
|
---|
204 | Below is an explanation of how the L</ImageInfo> function arguments are
|
---|
205 | interpreted:
|
---|
206 |
|
---|
207 | =over 4
|
---|
208 |
|
---|
209 | =item ExifTool ref
|
---|
210 |
|
---|
211 | L</ImageInfo> may be called with an ExifTool object if desired. The
|
---|
212 | advantage of using the object-oriented form is that the options may be set
|
---|
213 | before calling L</ImageInfo>, and the object may be used afterward to access
|
---|
214 | member functions. Must be the first argument if used.
|
---|
215 |
|
---|
216 | =item SCALAR
|
---|
217 |
|
---|
218 | The first scalar argument is taken to be the file name unless an earlier
|
---|
219 | argument specified the image data via a file reference (file ref) or data
|
---|
220 | reference (SCALAR ref). The remaining scalar arguments are names of tags
|
---|
221 | for requested information. All tags are returned if no tags are specified.
|
---|
222 |
|
---|
223 | Tag names are case-insensitive and may be prefixed by optional group names
|
---|
224 | separated by colons. A group name may begin with a family number (ie.
|
---|
225 | '1IPTC:Keywords'), to restrict matches to a specific family. In the tag
|
---|
226 | name, a '?' matches any single character and a '*' matches zero or more
|
---|
227 | characters. Thus 'GROUP:*' represents all tags in a specific group.
|
---|
228 | Wildcards may not be used in group names, with the exception that a group
|
---|
229 | name of '*' may be used to extract all available instances of a tag
|
---|
230 | regardless of the L</Duplicates> setting (ie. '*:WhiteBalance'). Multiple
|
---|
231 | groups may be specified (ie. 'EXIF:Time:*' extracts all EXIF Time tags). And
|
---|
232 | finally, a leading '-' indicates a tag to be excluded (ie. '-IFD1:*'), or a
|
---|
233 | trailing '#' causes the ValueConv value to be returned for this tag.
|
---|
234 |
|
---|
235 | Note that keys in the returned information hash and elements of the returned
|
---|
236 | tag list are not necessarily the same as these tag names because group names
|
---|
237 | are removed, the case may be changed, and an instance number may be added.
|
---|
238 | For this reason it is best to use either the keys of the returned hash or
|
---|
239 | the elements of the tag array when accessing the tag values.
|
---|
240 |
|
---|
241 | See L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a complete
|
---|
242 | list of ExifTool tag names.
|
---|
243 |
|
---|
244 | =item File ref
|
---|
245 |
|
---|
246 | A reference to an open image file. If you use this method (or a SCALAR
|
---|
247 | reference) to access information in an image, the FileName and Directory
|
---|
248 | tags will not be returned. (Also, the FileSize, FileModifyDate and
|
---|
249 | FilePermissions tags will not be returned unless it is a plain file.) Image
|
---|
250 | processing begins at the current file position, and on return the file
|
---|
251 | position is unspecified. May be either a standard filehandle, or a
|
---|
252 | reference to a L<File::RandomAccess|File::RandomAccess> object. Note that
|
---|
253 | the file remains open and must be closed by the caller after L</ImageInfo>
|
---|
254 | returns.
|
---|
255 |
|
---|
256 | [Advanced: To allow a non-rewindable stream (ie. a network socket) to be
|
---|
257 | re-read after processing with ExifTool, first wrap the file reference in a
|
---|
258 | L<File::RandomAccess|File::RandomAccess> object, then pass this object to
|
---|
259 | L</ImageInfo>. The L<File::RandomAccess|File::RandomAccess> object will
|
---|
260 | buffer the file if necessary, and may be used to re-read the file after
|
---|
261 | L</ImageInfo> returns.]
|
---|
262 |
|
---|
263 | =item SCALAR ref
|
---|
264 |
|
---|
265 | A reference to image data in memory.
|
---|
266 |
|
---|
267 | =item ARRAY ref
|
---|
268 |
|
---|
269 | Reference to a list of tag names. On entry, any elements in the list are
|
---|
270 | added to the list of requested tags. Tags with names beginning with '-' are
|
---|
271 | excluded. On return, this list is updated to contain an ordered list of tag
|
---|
272 | keys for the returned information.
|
---|
273 |
|
---|
274 | There will be 1:1 correspondence between the requested tags and the returned
|
---|
275 | tag keys only if the L</Duplicates> option is 0 and L</Sort> is 'Input'.
|
---|
276 | (With L</Duplicates> enabled, there may be more entries in the returned list
|
---|
277 | of tag keys, and with other L</Sort> settings the entries may not be in the
|
---|
278 | same order as requested.)
|
---|
279 |
|
---|
280 | =item HASH ref
|
---|
281 |
|
---|
282 | Reference to a hash containing the options settings. See L</Options>
|
---|
283 | documentation below for a list of available options. Options specified
|
---|
284 | as arguments to L</ImageInfo> take precedence over L</Options> settings.
|
---|
285 |
|
---|
286 | =back
|
---|
287 |
|
---|
288 | =item Return Values:
|
---|
289 |
|
---|
290 | L</ImageInfo> returns a reference to a hash of tag key/value pairs. The tag
|
---|
291 | keys are identifiers, which are similar to the tag names but may have an
|
---|
292 | embedded instance number if multiple tags with the same name were extracted
|
---|
293 | from the image. Many of the ExifTool functions require a tag key as an
|
---|
294 | argument. Use L</GetTagName [static]> to get the tag name for a given tag
|
---|
295 | key. Note that the case of the tag names may not be the same as requested.
|
---|
296 | Here is a simple example to print out the information returned by
|
---|
297 | L</ImageInfo>:
|
---|
298 |
|
---|
299 | foreach (sort keys %$info) {
|
---|
300 | print "$_ => $$info{$_}\n";
|
---|
301 | }
|
---|
302 |
|
---|
303 | Values of the returned hash are usually simple scalars, but a scalar
|
---|
304 | reference is used to indicate binary data and an array reference may be used
|
---|
305 | to indicate a list. Also, a hash reference may be returned if the L</Struct>
|
---|
306 | option is used. Lists of values are joined by commas into a single
|
---|
307 | string only if the PrintConv option is enabled and the List option is
|
---|
308 | disabled (which are the defaults). Note that binary values are not
|
---|
309 | necessarily extracted unless specifically requested or the Binary option is
|
---|
310 | set. If not extracted the value is a reference to a string of the form
|
---|
311 | "Binary data ##### bytes".
|
---|
312 |
|
---|
313 | The code below gives an example of how to handle these return values, as
|
---|
314 | well as illustrating the use of other ExifTool functions:
|
---|
315 |
|
---|
316 | use Image::ExifTool;
|
---|
317 | my $exifTool = new Image::ExifTool;
|
---|
318 | $exifTool->Options(Unknown => 1);
|
---|
319 | my $info = $exifTool->ImageInfo('a.jpg');
|
---|
320 | my $group = '';
|
---|
321 | my $tag;
|
---|
322 | foreach $tag ($exifTool->GetFoundTags('Group0')) {
|
---|
323 | if ($group ne $exifTool->GetGroup($tag)) {
|
---|
324 | $group = $exifTool->GetGroup($tag);
|
---|
325 | print "---- $group ----\n";
|
---|
326 | }
|
---|
327 | my $val = $info->{$tag};
|
---|
328 | if (ref $val eq 'SCALAR') {
|
---|
329 | if ($$val =~ /^Binary data/) {
|
---|
330 | $val = "($$val)";
|
---|
331 | } else {
|
---|
332 | my $len = length($$val);
|
---|
333 | $val = "(Binary data $len bytes)";
|
---|
334 | }
|
---|
335 | }
|
---|
336 | printf("%-32s : %s\n", $exifTool->GetDescription($tag), $val);
|
---|
337 | }
|
---|
338 |
|
---|
339 | =item Notes:
|
---|
340 |
|
---|
341 | ExifTool returns all values as byte strings of encoded characters. Perl
|
---|
342 | wide characters are not used. See L</CHARACTER ENCODINGS> for details about
|
---|
343 | the encodings.
|
---|
344 |
|
---|
345 | As well as tags representing information extracted from the image,
|
---|
346 | the following tags generated by ExifTool may be returned:
|
---|
347 |
|
---|
348 | ExifToolVersion - The ExifTool version number.
|
---|
349 |
|
---|
350 | Error - An error message if the image could not be processed.
|
---|
351 |
|
---|
352 | Warning - A warning message if problems were encountered while
|
---|
353 | processing the image.
|
---|
354 |
|
---|
355 | =back
|
---|
356 |
|
---|
357 | =head2 Options
|
---|
358 |
|
---|
359 | Get/set ExifTool options. This function can be called to set the default
|
---|
360 | options for an ExifTool object. Options set this way are in effect for
|
---|
361 | all function calls but may be overridden by options passed as arguments
|
---|
362 | to some functions.
|
---|
363 |
|
---|
364 | The initial default options are obtained from values in the
|
---|
365 | %Image::ExifTool::UserDefined::Options hash if it exists. See the
|
---|
366 | .ExifTool_config file in the full ExifTool distribution for details.
|
---|
367 |
|
---|
368 | # exclude the 'OwnerName' tag from returned information
|
---|
369 | $exifTool->Options(Exclude => 'OwnerName');
|
---|
370 |
|
---|
371 | # only get information in EXIF or MakerNotes groups
|
---|
372 | $exifTool->Options(Group0 => ['EXIF', 'MakerNotes']);
|
---|
373 |
|
---|
374 | # ignore information from IFD1
|
---|
375 | $exifTool->Options(Group1 => '-IFD1');
|
---|
376 |
|
---|
377 | # sort by groups in family 2, and extract unknown tags
|
---|
378 | $exifTool->Options(Sort => 'Group2', Unknown => 1);
|
---|
379 |
|
---|
380 | # reset DateFormat option
|
---|
381 | $exifTool->Options(DateFormat => undef);
|
---|
382 |
|
---|
383 | # do not extract duplicate tag names
|
---|
384 | $oldSetting = $exifTool->Options(Duplicates => 0);
|
---|
385 |
|
---|
386 | # get current Verbose setting
|
---|
387 | $isVerbose = $exifTool->Options('Verbose');
|
---|
388 |
|
---|
389 | =over 4
|
---|
390 |
|
---|
391 | =item Inputs:
|
---|
392 |
|
---|
393 | 0) ExifTool object reference.
|
---|
394 |
|
---|
395 | 1) Option parameter name.
|
---|
396 |
|
---|
397 | 2) [optional] Option parameter value (may be undef to clear option).
|
---|
398 |
|
---|
399 | 3-N) [optional] Additional parameter/value pairs.
|
---|
400 |
|
---|
401 | =item Option Parameters:
|
---|
402 |
|
---|
403 | =over 4
|
---|
404 |
|
---|
405 | =item Binary
|
---|
406 |
|
---|
407 | Flag to extract the value data for all binary tags. Tag values representing
|
---|
408 | large binary data blocks (ie. ThumbnailImage) are not necessarily extracted
|
---|
409 | unless this option is set or the tag is specifically requested by name.
|
---|
410 | Default is 0.
|
---|
411 |
|
---|
412 | =item ByteOrder
|
---|
413 |
|
---|
414 | The byte order for newly created EXIF segments when writing. Note that if
|
---|
415 | EXIF information already exists, the existing order is maintained. Valid
|
---|
416 | values are 'MM', 'II' and undef. If ByteOrder is not defined (the default),
|
---|
417 | then the maker note byte order is used (if they are being copied), otherwise
|
---|
418 | big-endian ('MM') order is assumed. This can also be set via the
|
---|
419 | ExifByteOrder tag, but the ByteOrder option takes precedence if both are
|
---|
420 | set.
|
---|
421 |
|
---|
422 | =item Charset
|
---|
423 |
|
---|
424 | Character set for encoding character strings passed to/from ExifTool with
|
---|
425 | code points above U+007F. Default is UTF8. Valid values are listed below,
|
---|
426 | case is not significant:
|
---|
427 |
|
---|
428 | Value Alias(es) Description
|
---|
429 | ----------- --------------- ----------------------------------
|
---|
430 | UTF8 cp65001, UTF-8 UTF-8 characters
|
---|
431 | Latin cp1252, Latin1 Windows Latin1 (West European)
|
---|
432 | Latin2 cp1250 Windows Latin2 (Central European)
|
---|
433 | Cyrillic cp1251, Russian Windows Cyrillic
|
---|
434 | Greek cp1253 Windows Greek
|
---|
435 | Turkish cp1254 Windows Turkish
|
---|
436 | Hebrew cp1255 Windows Hebrew
|
---|
437 | Arabic cp1256 Windows Arabic
|
---|
438 | Baltic cp1257 Windows Baltic
|
---|
439 | Vietnam cp1258 Windows Vietnamese
|
---|
440 | Thai cp874 Windows Thai
|
---|
441 | MacRoman cp10000, Roman Macintosh Roman
|
---|
442 | MacLatin2 cp10029 Macintosh Latin2 (Central Europe)
|
---|
443 | MacCyrillic cp10007 Macintosh Cyrillic
|
---|
444 | MacGreek cp10006 Macintosh Greek
|
---|
445 | MacTurkish cp10081 Macintosh Turkish
|
---|
446 | MacRomanian cp10010 Macintosh Romanian
|
---|
447 | MacIceland cp10079 Macintosh Icelandic
|
---|
448 | MacCroatian cp10082 Macintosh Croatian
|
---|
449 |
|
---|
450 | Note that this option affects some types of information when reading/writing
|
---|
451 | the file and other types when getting/setting tag values, so it must be
|
---|
452 | defined for both types of access.
|
---|
453 |
|
---|
454 | =item CharsetID3
|
---|
455 |
|
---|
456 | Character encoding to assume for ID3v1 strings. By the specification ID3v1
|
---|
457 | strings should be encoded in ISO 8859-1 (essentially Latin), but some
|
---|
458 | applications may use local encoding instead. Default is Latin.
|
---|
459 |
|
---|
460 | =item CharsetIPTC
|
---|
461 |
|
---|
462 | Fallback IPTC character set to assume if IPTC information contains no
|
---|
463 | CodedCharacterSet tag. Possible values are the same as the L</Charset>
|
---|
464 | option. Default is Latin.
|
---|
465 |
|
---|
466 | Note that this option affects some types of information when reading/writing
|
---|
467 | the file and other types when getting/setting tag values, so it must be
|
---|
468 | defined for both types of access.
|
---|
469 |
|
---|
470 | =item CharsetPhotoshop
|
---|
471 |
|
---|
472 | Character encoding to assume for Photoshop IRB resource names. Default is
|
---|
473 | Latin.
|
---|
474 |
|
---|
475 | =item Compact
|
---|
476 |
|
---|
477 | Flag to write compact output. Default is 0. The XMP specification suggests
|
---|
478 | that the data be padded with blanks to allow in-place editing. With this
|
---|
479 | flag set the 2kB of padding is not written. Note that this only effects
|
---|
480 | embedded XMP since padding is never written for stand-alone XMP files.
|
---|
481 |
|
---|
482 | =item Composite
|
---|
483 |
|
---|
484 | Flag to calculate Composite tags automatically. Default is 1.
|
---|
485 |
|
---|
486 | =item Compress
|
---|
487 |
|
---|
488 | Flag to write new values in compressed format if possible. Has no effect
|
---|
489 | unless Compress::Zlib is installed. Default is 0.
|
---|
490 |
|
---|
491 | =item CoordFormat
|
---|
492 |
|
---|
493 | Format for printing GPS coordinates. This is a printf format string with
|
---|
494 | specifiers for degrees, minutes and seconds in that order, however minutes
|
---|
495 | and seconds may be omitted. For example, the following table gives the
|
---|
496 | output for the same coordinate using various formats:
|
---|
497 |
|
---|
498 | CoordFormat Example Output
|
---|
499 | ------------------- ------------------
|
---|
500 | q{%d deg %d' %.2f"} 54 deg 59' 22.80" (default for reading)
|
---|
501 | q{%d %d %.8f} 54 59 22.80000000 (default for copying)
|
---|
502 | q{%d deg %.4f min} 54 deg 59.3800 min
|
---|
503 | q{%.6f degrees} 54.989667 degrees
|
---|
504 |
|
---|
505 | Note: To avoid loss of precision, the default coordinate format is
|
---|
506 | different when copying tags with L</SetNewValuesFromFile>.
|
---|
507 |
|
---|
508 | =item DateFormat
|
---|
509 |
|
---|
510 | Format for printing date/time values. See C<strftime> in the L<POSIX>
|
---|
511 | package for details about the format string. The default is similar to a
|
---|
512 | format of "%Y:%m:%d %H:%M:%S". If date can not be converted, value is left
|
---|
513 | unchanged unless the StrictDate option is set. Timezones are ignored.
|
---|
514 |
|
---|
515 | =item Duplicates
|
---|
516 |
|
---|
517 | Flag to return values from tags with duplicate names when extracting
|
---|
518 | information. Default is 1.
|
---|
519 |
|
---|
520 | =item Escape
|
---|
521 |
|
---|
522 | Escape special characters in extracted values for HTML or XML. Also
|
---|
523 | unescapes HTML or XML character entities in input values passed to
|
---|
524 | L</SetNewValue>. Valid settings are 'HTML', 'XML' or undef. Default is
|
---|
525 | undef.
|
---|
526 |
|
---|
527 | =item Exclude
|
---|
528 |
|
---|
529 | Exclude specified tags from tags extracted from an image. The option value
|
---|
530 | is either a tag name or reference to a list of tag names to exclude. The
|
---|
531 | case of tag names is not significant. This option is ignored for
|
---|
532 | specifically requested tags. Tags may also be excluded by preceeding their
|
---|
533 | name with a '-' in the arguments to L</ImageInfo>.
|
---|
534 |
|
---|
535 | =item ExtractEmbedded
|
---|
536 |
|
---|
537 | Flag to extract information from embedded documents in EPS and PDF files,
|
---|
538 | embedded MPF images in JPEG and MPO files, streaming metadata in AVCHD
|
---|
539 | videos, and the resource fork of Mac OS files. Default is 0.
|
---|
540 |
|
---|
541 | =item FastScan
|
---|
542 |
|
---|
543 | Flag to increase speed of extracting information from JPEG images. With
|
---|
544 | this option set to 1, ExifTool will not scan to the end of a JPEG image to
|
---|
545 | check for an AFCP, CanonVRD, FotoStation, PhotoMechanic, MIE or PreviewImage
|
---|
546 | trailer. This also stops the parsing after the first comment in GIF images,
|
---|
547 | and at the audio/video data with RIFF-format files (AVI, WAV, etc), so any
|
---|
548 | trailing metadata (ie. XMP written by some utilities) may be missed. When
|
---|
549 | combined with the ScanForXMP option, prevents scanning for XMP in recognized
|
---|
550 | file types. With a value of 2, ExifTool will also avoid extracting any EXIF
|
---|
551 | MakerNote information. Default is 0.
|
---|
552 |
|
---|
553 | =item FixBase
|
---|
554 |
|
---|
555 | Fix maker notes base offset. A common problem with image editing software
|
---|
556 | is that offsets in the maker notes are not adjusted properly when the file
|
---|
557 | is modified. This may cause the wrong values to be extracted for some maker
|
---|
558 | note entries when reading the edited file. FixBase specifies an integer
|
---|
559 | value to be added to the maker notes base offset. It may also be set to the
|
---|
560 | empty string ('') for ExifTool will take its best guess at the correct base,
|
---|
561 | or undef (the default) for no base adjustment.
|
---|
562 |
|
---|
563 | =item GeoMaxIntSecs
|
---|
564 |
|
---|
565 | Maximum interpolation time in seconds for geotagging. Geotagging fails if
|
---|
566 | the Geotime value lies between two fixes in the same track which are
|
---|
567 | separated by a number of seconds greater than this. Default is 1800.
|
---|
568 |
|
---|
569 | =item GeoMaxExtSecs
|
---|
570 |
|
---|
571 | Maximum extrapolation time in seconds for geotagging. Geotagging fails if
|
---|
572 | the Geotime value lies outside a GPS track by a number of seconds greater
|
---|
573 | than this. Default is 1800.
|
---|
574 |
|
---|
575 | =item GeoMaxHDOP
|
---|
576 |
|
---|
577 | Maximum Horizontal (2D) Dilution Of Precision for geotagging. GPS fixes are
|
---|
578 | ignored if the HDOP is greater than this. Default is undef.
|
---|
579 |
|
---|
580 | =item GeoMaxPDOP
|
---|
581 |
|
---|
582 | Maximum Position (3D) Dilution Of Precision for geotagging. GPS fixes are
|
---|
583 | ignored if the PDOP is greater than this. Default is undef.
|
---|
584 |
|
---|
585 | =item GeoMinSats
|
---|
586 |
|
---|
587 | Minimum number of satellites for geotagging. GPS fixes are ignored if the
|
---|
588 | number of acquired satellites is less than this. Default is undef.
|
---|
589 |
|
---|
590 | =item Group#
|
---|
591 |
|
---|
592 | Extract tags only for specified groups in family # (Group0 assumed if #
|
---|
593 | not given). The option value may be a single group name or a reference
|
---|
594 | to a list of groups. Case is significant in group names. Specify a group
|
---|
595 | to be excluded by preceding group name with a '-'. See L</GetGroup> for a
|
---|
596 | description of group families, and L</GetAllGroups [static]> for lists of
|
---|
597 | group names.
|
---|
598 |
|
---|
599 | =item HtmlDump
|
---|
600 |
|
---|
601 | Dump information in hex to dynamic HTML web page. The value may be 0-3 for
|
---|
602 | increasingly larger limits on the maximum block size. Default is 0. Output
|
---|
603 | goes to the file specified by the TextOut option (\*STDOUT by default).
|
---|
604 |
|
---|
605 | =item HtmlDumpBase
|
---|
606 |
|
---|
607 | Specifies base for HTML dump offsets. If not defined, the EXIF/TIFF base
|
---|
608 | offset is used. Set to 0 for absolute offsets. Default is undef.
|
---|
609 |
|
---|
610 | =item IgnoreMinorErrors
|
---|
611 |
|
---|
612 | Flag to ignore minor errors. Causes minor errors to be downgraded to
|
---|
613 | warnings, and minor warnings to be ignored. This option is provided mainly
|
---|
614 | to allow writing of files when minor errors occur, but by ignoring some
|
---|
615 | minor warnings the behaviour of ExifTool may be changed to allow some
|
---|
616 | questionable operations to proceed (such as extracting thumbnail and preview
|
---|
617 | images even if they don't have a recognizable header). Minor
|
---|
618 | errors/warnings are denoted by '[minor]' at the start of the message.
|
---|
619 |
|
---|
620 | =item Lang
|
---|
621 |
|
---|
622 | Localized language for exiftool tag descriptions, etc. Available languages
|
---|
623 | are given by the Image::ExifTool::Lang module names (ie. 'fr'). If the
|
---|
624 | specified language isn't available, the option is not changed. May be set
|
---|
625 | to undef to select the built-in default language. Default is 'en'.
|
---|
626 |
|
---|
627 | =item LargeFileSupport
|
---|
628 |
|
---|
629 | Flag to indicate that 64-bit file offsets are supported on this system.
|
---|
630 | Default is 0.
|
---|
631 |
|
---|
632 | =item List
|
---|
633 |
|
---|
634 | Flag to extract lists of PrintConv values into arrays instead of joining
|
---|
635 | them into a string of values. The L</ListSep> option specifies the
|
---|
636 | separator used when combining values. Default is 0.
|
---|
637 |
|
---|
638 | =item ListSep
|
---|
639 |
|
---|
640 | Separator string used to join lists of PrintConv values when L</List> option
|
---|
641 | is not set. Default is ', '.
|
---|
642 |
|
---|
643 | =item ListSplit
|
---|
644 |
|
---|
645 | Regular expression used to split values of list-type tags into individual
|
---|
646 | items when writing. (ie. use ',\\s*' to split a comma-separated list.)
|
---|
647 | Default is undef.
|
---|
648 |
|
---|
649 | =item MakerNotes
|
---|
650 |
|
---|
651 | Option to extract MakerNotes and other writable subdirectories (such as
|
---|
652 | PrintIM) as a data block. Normally when the MakerNotes are extracted they
|
---|
653 | are rebuilt to include data outside the boundaries of the original maker
|
---|
654 | note data block, but a value of 2 disables this feature. Possible values
|
---|
655 | are:
|
---|
656 |
|
---|
657 | 0 - Do not extract writable subdirectories (default)
|
---|
658 | 1 - Extract and rebuild maker notes into self-contained block
|
---|
659 | 2 - Extract without rebuilding maker notes
|
---|
660 |
|
---|
661 | =item MissingTagValue
|
---|
662 |
|
---|
663 | Value for missing tags in expressions evaluated by L</SetNewValuesFromFile>.
|
---|
664 | If not set, a minor error is issued for missing values, or the value is set
|
---|
665 | to '' if L</IgnoreMinorErrors> is set. Default is undef.
|
---|
666 |
|
---|
667 | =item Password
|
---|
668 |
|
---|
669 | Password for processing password-protected PDF documents. Ignored if a
|
---|
670 | password is not required. Character encoding of the password is determined
|
---|
671 | by the value of the Charset option at processing time. Default is undef.
|
---|
672 |
|
---|
673 | =item PrintConv
|
---|
674 |
|
---|
675 | Flag to enable automatic print conversion. Also enables inverse
|
---|
676 | print conversion for writing. Default is 1.
|
---|
677 |
|
---|
678 | =item ScanForXMP
|
---|
679 |
|
---|
680 | Flag for scan all files (even unrecognized formats) for XMP information
|
---|
681 | unless XMP was already found in the file. When combined with the FastScan
|
---|
682 | option, only unrecognized file types are scanned for XMP. Default is 0.
|
---|
683 |
|
---|
684 | =item Sort
|
---|
685 |
|
---|
686 | Specifies order to sort tags in returned list:
|
---|
687 |
|
---|
688 | Input - Sort in same order as input tag arguments (default)
|
---|
689 | Alpha - Sort alphabetically
|
---|
690 | File - Sort in order that tags were found in the file
|
---|
691 | Group# - Sort by tag group, where # is zero or more family
|
---|
692 | numbers separated by colons. If # is not specified,
|
---|
693 | Group0 is assumed. See GetGroup for a description
|
---|
694 | of group families.
|
---|
695 |
|
---|
696 | =item StrictDate
|
---|
697 |
|
---|
698 | Flag to return undefined value for any date which can't be converted when
|
---|
699 | the DateFormat option is used. Default is undef.
|
---|
700 |
|
---|
701 | =item Struct
|
---|
702 |
|
---|
703 | Flag to return XMP structures as hash references instead of flattening into
|
---|
704 | individual tags. If not defined (the default), tags are flattened when
|
---|
705 | reading (with L<ExtractInfo>), and structured when copying (with
|
---|
706 | L</SetNewValuesFromFile>). Has no effect when writing since both flattened
|
---|
707 | and structured tags may always be written. Possible values are:
|
---|
708 |
|
---|
709 | undef - Read flattened tags, copy structured tags (default)
|
---|
710 | 0 - Read and copy flattened tags
|
---|
711 | 1 - Read and copy structured tags
|
---|
712 |
|
---|
713 | =item TextOut
|
---|
714 |
|
---|
715 | Output file reference for Verbose and HtmlDump options. Default is
|
---|
716 | \*STDOUT.
|
---|
717 |
|
---|
718 | =item Unknown
|
---|
719 |
|
---|
720 | Flag to get the values of unknown tags. If set to 1, unknown tags are
|
---|
721 | extracted from EXIF (or other tagged-format) directories. If set to 2,
|
---|
722 | unknown tags are also extracted from binary data blocks. Default is 0.
|
---|
723 |
|
---|
724 | =item Verbose
|
---|
725 |
|
---|
726 | Print verbose messages to file specified by TextOut option. Value may be
|
---|
727 | from 0 to 5 for increasingly verbose messages. Default is 0. With the
|
---|
728 | verbose option set, messages are printed to the console as the file is
|
---|
729 | parsed. Level 1 prints the tag names and raw values. Level 2 adds more
|
---|
730 | details about the tags. Level 3 adds a hex dump of the tag data, but with
|
---|
731 | limits on the number of bytes dumped. Levels 4 and 5 remove the dump limit
|
---|
732 | on tag values and JPEG segment data respectively.
|
---|
733 |
|
---|
734 | =back
|
---|
735 |
|
---|
736 | =item Return Values:
|
---|
737 |
|
---|
738 | The original value of the last specified parameter.
|
---|
739 |
|
---|
740 | =back
|
---|
741 |
|
---|
742 | =head2 ClearOptions
|
---|
743 |
|
---|
744 | Reset all options to their default values. Loads user-defined default
|
---|
745 | option values from the %Image::ExifTool::UserDefined::Options hash in the
|
---|
746 | .ExifTool_config file if it exists.
|
---|
747 |
|
---|
748 | $exifTool->ClearOptions();
|
---|
749 |
|
---|
750 | =over 4
|
---|
751 |
|
---|
752 | =item Inputs:
|
---|
753 |
|
---|
754 | 0) ExifTool object reference
|
---|
755 |
|
---|
756 | =item Return Values:
|
---|
757 |
|
---|
758 | (none)
|
---|
759 |
|
---|
760 | =back
|
---|
761 |
|
---|
762 | =head2 ExtractInfo
|
---|
763 |
|
---|
764 | Extract all meta information from an image.
|
---|
765 |
|
---|
766 | $success = $exifTool->ExtractInfo('image.jpg', \%options);
|
---|
767 |
|
---|
768 | =over 4
|
---|
769 |
|
---|
770 | =item Inputs:
|
---|
771 |
|
---|
772 | L</ExtractInfo> takes exactly the same arguments as L</ImageInfo>. The only
|
---|
773 | difference is that a list of tag keys is not returned if an ARRAY reference
|
---|
774 | is given. The following options are effective in the call to
|
---|
775 | L</ExtractInfo>:
|
---|
776 |
|
---|
777 | Binary, Charset, CharsetID3, CharsetIPTC, Composite, ExtractEmbedded,
|
---|
778 | FastScan, FixBase, HtmlDump, HtmlDumpBase, IgnoreMinorErrors, Lang,
|
---|
779 | LargeFileSupport, MakerNotes, ScanForXMP, Struct, TextOut, Unknown and
|
---|
780 | Verbose.
|
---|
781 |
|
---|
782 | =item Return Value:
|
---|
783 |
|
---|
784 | 1 if this was a recognized file format, 0 otherwise (and 'Error' tag set).
|
---|
785 |
|
---|
786 | =back
|
---|
787 |
|
---|
788 | =head2 GetInfo
|
---|
789 |
|
---|
790 | L</GetInfo> is called to return meta information after it has been extracted
|
---|
791 | from the image by a previous call to L</ExtractInfo> or L</ImageInfo>. This
|
---|
792 | function may be called repeatedly after a single call to L</ExtractInfo> or
|
---|
793 | L</ImageInfo>.
|
---|
794 |
|
---|
795 | # get image width and hieght only
|
---|
796 | $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');
|
---|
797 |
|
---|
798 | # get information for all tags in list (list updated with tags found)
|
---|
799 | $info = $exifTool->GetInfo(\@ioTagList);
|
---|
800 |
|
---|
801 | # get all information in Author or Location groups
|
---|
802 | $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});
|
---|
803 |
|
---|
804 | =over 4
|
---|
805 |
|
---|
806 | =item Inputs:
|
---|
807 |
|
---|
808 | Inputs are the same as L</ExtractInfo> and L</ImageInfo> except that an
|
---|
809 | image can not be specified. Options in effect are:
|
---|
810 |
|
---|
811 | Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Group#, Lang,
|
---|
812 | List, ListSep, PrintConv, Sort (if a tag list reference is given) and
|
---|
813 | StrictDate.
|
---|
814 |
|
---|
815 | =item Return Value:
|
---|
816 |
|
---|
817 | Reference to information hash, the same as with L</ImageInfo>.
|
---|
818 |
|
---|
819 | =back
|
---|
820 |
|
---|
821 | =head2 WriteInfo
|
---|
822 |
|
---|
823 | Write meta information to a file. The specified source file is rewritten to
|
---|
824 | the same-type destination file with new information as specified by previous
|
---|
825 | calls to L</SetNewValue>. The necessary segments and/or directories are
|
---|
826 | created in the destination file as required to store the specified
|
---|
827 | information. May be called repeatedly to write the same information to
|
---|
828 | additional files without the need to call L</SetNewValue> again.
|
---|
829 |
|
---|
830 | # add information to a source file, writing output to new file
|
---|
831 | $exifTool->WriteInfo($srcfile, $dstfile);
|
---|
832 |
|
---|
833 | # create XMP data file from scratch
|
---|
834 | $exifTool->WriteInfo(undef, $dstfile, 'XMP');
|
---|
835 |
|
---|
836 | # overwrite file (you do have backups, right?)
|
---|
837 | $exifTool->WriteInfo($srcfile);
|
---|
838 |
|
---|
839 | =over 4
|
---|
840 |
|
---|
841 | =item Inputs:
|
---|
842 |
|
---|
843 | 0) ExifTool object reference
|
---|
844 |
|
---|
845 | 1) Source file name, file reference, scalar reference, or undef to create a
|
---|
846 | file from scratch
|
---|
847 |
|
---|
848 | 2) [optional] Destination file name, file reference, scalar reference, or
|
---|
849 | undef to overwrite the original file
|
---|
850 |
|
---|
851 | 3) [optional] Destination file type
|
---|
852 |
|
---|
853 | =item Return Value:
|
---|
854 |
|
---|
855 | 1 if file was written OK, 2 if file was written but no changes made, 0 on
|
---|
856 | file write error.
|
---|
857 |
|
---|
858 | If an error code is returned, an Error tag is set and GetValue('Error') can
|
---|
859 | be called to obtain the error description. A Warning tag may be set even if
|
---|
860 | this routine is successful. Calling WriteInfo clears any pre-existing Error
|
---|
861 | and Warning tags.
|
---|
862 |
|
---|
863 | $errorMessage = $exifTool->GetValue('Error');
|
---|
864 | $warningMessage = $exifTool->GetValue('Warning');
|
---|
865 |
|
---|
866 | =item Notes:
|
---|
867 |
|
---|
868 | The source file name may be undefined to create a file from scratch
|
---|
869 | (currently only XMP, MIE, ICC, VRD and EXIF files can be created in this way
|
---|
870 | -- see L</CanCreate> for details). If undefined, the destination file type
|
---|
871 | is required unless the type can be determined from the destination file
|
---|
872 | name.
|
---|
873 |
|
---|
874 | If a destination file name is given, the specified file must not exist
|
---|
875 | because an existing destination file will not be overwritten. The
|
---|
876 | destination file name may be undefined to overwrite the original file (make
|
---|
877 | sure you have backups!). In this case, if a source file name is provided, a
|
---|
878 | temporary file is created and renamed to replace the source file if no
|
---|
879 | errors occurred while writing. Otherwise, if a source file reference or
|
---|
880 | scalar reference is used, the image is first written to memory then copied
|
---|
881 | back to replace the original if there were no errors.
|
---|
882 |
|
---|
883 | The destination file type is only used if the source file is undefined.
|
---|
884 |
|
---|
885 | On Mac OS systems, the file resource fork is preserved if this routine is
|
---|
886 | called with a source file name.
|
---|
887 |
|
---|
888 | =back
|
---|
889 |
|
---|
890 | The following ExifTool options are effective in the call to L</WriteInfo>:
|
---|
891 |
|
---|
892 | ByteOrder, Charset, CharsetID3, CharsetIPTC, Compact, Compress, FixBase,
|
---|
893 | IgnoreMinorErrors and Verbose.
|
---|
894 |
|
---|
895 | =head2 CombineInfo
|
---|
896 |
|
---|
897 | Combine information from more than one information hash into a single hash.
|
---|
898 |
|
---|
899 | $info = $exifTool->CombineInfo($info1, $info2, $info3);
|
---|
900 |
|
---|
901 | =over 4
|
---|
902 |
|
---|
903 | =item Inputs:
|
---|
904 |
|
---|
905 | 0) ExifTool object reference
|
---|
906 |
|
---|
907 | 1-N) Information hash references
|
---|
908 |
|
---|
909 | =back
|
---|
910 |
|
---|
911 | If the Duplicates option is disabled and duplicate tags exist, the order of
|
---|
912 | the hashes is significant. In this case, the value used is the first value
|
---|
913 | found as the hashes are scanned in order of input. The Duplicates option
|
---|
914 | is the only option that is in effect for this function.
|
---|
915 |
|
---|
916 | =head2 GetTagList
|
---|
917 |
|
---|
918 | Get a sorted list of tags from the specified information hash or tag list.
|
---|
919 |
|
---|
920 | @tags = $exifTool->GetTagList($info, 'Group0');
|
---|
921 |
|
---|
922 | =over 4
|
---|
923 |
|
---|
924 | =item Inputs:
|
---|
925 |
|
---|
926 | 0) ExifTool object reference,
|
---|
927 |
|
---|
928 | 1) [optional] Information hash reference or tag list reference,
|
---|
929 |
|
---|
930 | 2) [optional] Sort order ('File', 'Input', 'Alpha' or 'Group#').
|
---|
931 |
|
---|
932 | If the information hash or tag list reference is not provided, then the list
|
---|
933 | of found tags from the last call to L</ImageInfo>, L</ExtractInfo> or
|
---|
934 | L</GetInfo> is used instead, and the result is the same as if
|
---|
935 | L</GetFoundTags> was called. If sort order is not specified, the sort order
|
---|
936 | is taken from the current options settings.
|
---|
937 |
|
---|
938 | =item Return Values:
|
---|
939 |
|
---|
940 | A list of tag keys in the specified order.
|
---|
941 |
|
---|
942 | =back
|
---|
943 |
|
---|
944 | =head2 GetFoundTags
|
---|
945 |
|
---|
946 | Get list of found tags in specified sort order. The found tags are the tags
|
---|
947 | for the information obtained from the most recent call to L</ImageInfo>,
|
---|
948 | L</ExtractInfo> or L</GetInfo> for this object.
|
---|
949 |
|
---|
950 | @tags = $exifTool->GetFoundTags('File');
|
---|
951 |
|
---|
952 | =over 4
|
---|
953 |
|
---|
954 | =item Inputs:
|
---|
955 |
|
---|
956 | 0) ExifTool object reference
|
---|
957 |
|
---|
958 | 1) [optional] Sort order ('File', 'Input', 'Alpha' or 'Group#')
|
---|
959 |
|
---|
960 | If sort order is not specified, the sort order from the ExifTool options is
|
---|
961 | used.
|
---|
962 |
|
---|
963 | =item Return Values:
|
---|
964 |
|
---|
965 | A list of tag keys in the specified order.
|
---|
966 |
|
---|
967 | =back
|
---|
968 |
|
---|
969 | =head2 GetRequestedTags
|
---|
970 |
|
---|
971 | Get list of requested tags. These are the tags that were specified in the
|
---|
972 | arguments of the most recent call to L</ImageInfo>, L</ExtractInfo> or
|
---|
973 | L</GetInfo>, including tags specified via a tag list reference. Shortcut
|
---|
974 | tags are expanded in the list.
|
---|
975 |
|
---|
976 | @tags = $exifTool->GetRequestedTags();
|
---|
977 |
|
---|
978 | =over 4
|
---|
979 |
|
---|
980 | =item Inputs:
|
---|
981 |
|
---|
982 | (none)
|
---|
983 |
|
---|
984 | =item Return Values:
|
---|
985 |
|
---|
986 | List of requested tag keys in the same order that the tags were specified.
|
---|
987 | Note that this list will be empty if tags were not specifically requested
|
---|
988 | (ie. If extracting all tags).
|
---|
989 |
|
---|
990 | =back
|
---|
991 |
|
---|
992 | =head2 GetValue
|
---|
993 |
|
---|
994 | Get the value of a specified tag. The returned value is either the
|
---|
995 | human-readable (PrintConv) value, the converted machine-readable (ValueConv)
|
---|
996 | value, or the original raw (Raw) value. If the value type is not specified,
|
---|
997 | the PrintConv value is returned if the PrintConv option is set, otherwise
|
---|
998 | the ValueConv value is returned. The PrintConv values are same as the
|
---|
999 | values returned by L</ImageInfo> and L</GetInfo> in the tag/value hash
|
---|
1000 | unless the PrintConv option is disabled.
|
---|
1001 |
|
---|
1002 | Tags which represent lists of multiple values (as may happen with 'Keywords'
|
---|
1003 | for example) are handled specially. In scalar context, the returned
|
---|
1004 | PrintConv value for these tags is either a string of values or a list
|
---|
1005 | reference (depending on the List option setting), and the ValueConv value is
|
---|
1006 | always a list reference. But in list context, L</GetValue> always returns
|
---|
1007 | the list itself.
|
---|
1008 |
|
---|
1009 | Note that L</GetValue> requires a case-sensitive tag key as an argument. To
|
---|
1010 | retrieve tag information based on a case-insensitive tag name (with an
|
---|
1011 | optional group specifier), use L</GetInfo> instead.
|
---|
1012 |
|
---|
1013 | # PrintConv example
|
---|
1014 | my $val = $exifTool->GetValue($tag);
|
---|
1015 | if (ref $val eq 'SCALAR') {
|
---|
1016 | print "$tag = (unprintable value)\n";
|
---|
1017 | } else {
|
---|
1018 | print "$tag = $val\n";
|
---|
1019 | }
|
---|
1020 |
|
---|
1021 | # ValueConv examples
|
---|
1022 | my $val = $exifTool->GetValue($tag, 'ValueConv');
|
---|
1023 | if (ref $val eq 'ARRAY') {
|
---|
1024 | print "$tag is a list of values\n";
|
---|
1025 | } elsif (ref $val eq 'SCALAR') {
|
---|
1026 | print "$tag represents binary data\n";
|
---|
1027 | } else {
|
---|
1028 | print "$tag is a simple scalar\n";
|
---|
1029 | }
|
---|
1030 |
|
---|
1031 | my @keywords = $exifTool->GetValue('Keywords', 'ValueConv');
|
---|
1032 |
|
---|
1033 | The following options are in effect when <L/GetValue> is called:
|
---|
1034 |
|
---|
1035 | Charset, CoordFormat, DateFormat, Escape, Lang, List, ListSep, PrintConv and
|
---|
1036 | StrictDate.
|
---|
1037 |
|
---|
1038 | =over 4
|
---|
1039 |
|
---|
1040 | =item Inputs:
|
---|
1041 |
|
---|
1042 | 0) ExifTool object reference
|
---|
1043 |
|
---|
1044 | 1) Tag key
|
---|
1045 |
|
---|
1046 | 2) [optional] Value type, 'PrintConv', 'ValueConv', 'Both' or 'Raw'
|
---|
1047 |
|
---|
1048 | The default value type is 'PrintConv' if the PrintConv option is set,
|
---|
1049 | otherwise the default is 'ValueConv'. A value type of 'Both' returns both
|
---|
1050 | ValueConv and PrintConv values as a list.
|
---|
1051 |
|
---|
1052 | =item Return Values:
|
---|
1053 |
|
---|
1054 | The value of the specified tag. If the tag represents a list of values and
|
---|
1055 | the List option is disabled then PrintConv returns a string of values,
|
---|
1056 | otherwise a reference to the list is returned in scalar context. The list
|
---|
1057 | itself is returned in list context. Values may also be scalar references to
|
---|
1058 | binary data, or hash references if the Struct option is set.
|
---|
1059 |
|
---|
1060 | Note: It is possible for L</GetValue> to return an undefined ValueConv or
|
---|
1061 | PrintConv value (or an empty list in list context) even if the tag exists,
|
---|
1062 | since it is possible for these conversions to yield undefined values.
|
---|
1063 |
|
---|
1064 | =back
|
---|
1065 |
|
---|
1066 | =head2 SetNewValue
|
---|
1067 |
|
---|
1068 | Set the new value for a tag. The routine may be called multiple times to
|
---|
1069 | set the values of many tags before using L</WriteInfo> to write the new
|
---|
1070 | values to an image.
|
---|
1071 |
|
---|
1072 | For list-type tags (like Keywords), either call repeatedly with the same tag
|
---|
1073 | name for each value, or call with a reference to the list of values.
|
---|
1074 |
|
---|
1075 | # set a new value for a tag (errors go to STDERR)
|
---|
1076 | $success = $exifTool->SetNewValue($tag, $value);
|
---|
1077 |
|
---|
1078 | # set a new value and capture any error message
|
---|
1079 | ($success, $errStr) = $exifTool->SetNewValue($tag, $value);
|
---|
1080 |
|
---|
1081 | # delete information for specified tag if it exists in image
|
---|
1082 | # (also resets AddValue and DelValue options for this tag)
|
---|
1083 | $exifTool->SetNewValue($tag);
|
---|
1084 |
|
---|
1085 | # reset all values from previous calls to SetNewValue()
|
---|
1086 | $exifTool->SetNewValue();
|
---|
1087 |
|
---|
1088 | # delete a specific keyword
|
---|
1089 | $exifTool->SetNewValue('Keywords', $word, DelValue => 1);
|
---|
1090 |
|
---|
1091 | # set keywords (a List-type tag) with two new values
|
---|
1092 | $exifTool->SetNewValue(Keywords => 'word1');
|
---|
1093 | $exifTool->SetNewValue(Keywords => 'word2');
|
---|
1094 | # equivalent, but set both in one call using an array reference
|
---|
1095 | $exifTool->SetNewValue(Keywords => ['word1','word2']);
|
---|
1096 |
|
---|
1097 | # add a keyword without replacing existing keywords in the file
|
---|
1098 | $exifTool->SetNewValue(Keywords => $word, AddValue => 1);
|
---|
1099 |
|
---|
1100 | # set a tag in a specific group
|
---|
1101 | $exifTool->SetNewValue(Headline => $val, Group => 'XMP');
|
---|
1102 | $exifTool->SetNewValue('XMP:Headline' => $val); # (equivalent)
|
---|
1103 |
|
---|
1104 | # shift original date/time back by 1 hour
|
---|
1105 | $exifTool->SetNewValue(DateTimeOriginal => '1:00', Shift => -1);
|
---|
1106 |
|
---|
1107 | # write a tag only if it had a specific value
|
---|
1108 | # (the order of the following calls is not significant)
|
---|
1109 | $exifTool->SetNewValue(Title => $oldVal, DelValue => 1);
|
---|
1110 | $exifTool->SetNewValue(Title => $newVal);
|
---|
1111 |
|
---|
1112 | # write tag by numerical value
|
---|
1113 | $exifTool->SetNewValue(Orientation => 6, Type => 'ValueConv');
|
---|
1114 | $exifTool->SetNewValue('Orientation#' => 6); # (equivalent)
|
---|
1115 |
|
---|
1116 | # delete all but EXIF tags
|
---|
1117 | $exifTool->SetNewValue('*'); # delete all...
|
---|
1118 | $exifTool->SetNewValue('EXIF:*', undef, Replace => 2); # ...but EXIF
|
---|
1119 |
|
---|
1120 | # write structured information as a HASH reference
|
---|
1121 | $exifTool->SetNewValue('XMP:Flash' => {
|
---|
1122 | mode => 'on',
|
---|
1123 | fired => 'true',
|
---|
1124 | return => 'not'
|
---|
1125 | });
|
---|
1126 |
|
---|
1127 | # write structured information as a serialized string
|
---|
1128 | $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}');
|
---|
1129 |
|
---|
1130 | (See L<http://owl.phy.queensu.ca/~phil/exiftool/struct.html#Serialize> for
|
---|
1131 | a description of the structure serialization technique.)
|
---|
1132 |
|
---|
1133 | =over 4
|
---|
1134 |
|
---|
1135 | =item Inputs:
|
---|
1136 |
|
---|
1137 | 0) ExifTool object reference
|
---|
1138 |
|
---|
1139 | 1) [optional] Tag key or tag name, or undef to clear all new values. A tag
|
---|
1140 | name of '*' can be used when deleting tags to delete all tags, or all tags
|
---|
1141 | in a specified group. The tag name may be prefixed by group name, separated
|
---|
1142 | by a colon (ie. 'EXIF:Artist'), which is equivalent to using a Group option
|
---|
1143 | argument. Also, a '#' may be appended to the tag name (ie.
|
---|
1144 | 'EXIF:Orientation#'), with the same effect as setting Type to 'ValueConv'.
|
---|
1145 |
|
---|
1146 | 2) [optional] New value for tag. Undefined to delete tag from file. May be
|
---|
1147 | a scalar, scalar reference, list reference to set a list of values, or hash
|
---|
1148 | reference for a structure. Integer values may be specified as a hexadecimal
|
---|
1149 | string (with a leading '0x'), and simple rational values may be specified in
|
---|
1150 | fractional form (ie. '4/10'). Structure tags may be specified either as a
|
---|
1151 | hash reference or a serialized string (see the last two examples above).
|
---|
1152 |
|
---|
1153 | 3-N) [optional] SetNewValue option/value pairs (see below).
|
---|
1154 |
|
---|
1155 | =item SetNewValue Options:
|
---|
1156 |
|
---|
1157 | =over 4
|
---|
1158 |
|
---|
1159 | =item AddValue
|
---|
1160 |
|
---|
1161 | Specifies that the value be added to an existing list rather than replacing
|
---|
1162 | the list. Valid values are 0 or 1. Default is 0.
|
---|
1163 |
|
---|
1164 | =item DelValue
|
---|
1165 |
|
---|
1166 | Delete the existing tag if it has the specified value. Valid values are
|
---|
1167 | 0 or 1. Default is 0.
|
---|
1168 |
|
---|
1169 | =item EditGroup
|
---|
1170 |
|
---|
1171 | Create tags in existing groups only. Don't create new group. Valid values
|
---|
1172 | are 0 and 1. Default is 0.
|
---|
1173 |
|
---|
1174 | =item EditOnly
|
---|
1175 |
|
---|
1176 | Edit tag only if it already exists. Don't create new tag. Valid values are
|
---|
1177 | 0 and 1. Default is 0.
|
---|
1178 |
|
---|
1179 | =item Group
|
---|
1180 |
|
---|
1181 | Specifies group name where tag should be written. If not specified, tag is
|
---|
1182 | written to highest priority group as specified by L</SetNewGroups>. Any
|
---|
1183 | family 0 or 1 group name may be used. Case is not significant.
|
---|
1184 |
|
---|
1185 | =item NoShortcut
|
---|
1186 |
|
---|
1187 | Disables default behaviour of looking up tag in shortcuts if not found
|
---|
1188 | otherwise.
|
---|
1189 |
|
---|
1190 | =item Protected
|
---|
1191 |
|
---|
1192 | Bit mask for tag protection levels to write. Bit 0x01 allows writing of
|
---|
1193 | 'unsafe' tags (ie. tags not copied automatically via
|
---|
1194 | L</SetNewValuesFromFile>). Bit 0x02 allows writing of 'protected' tags, and
|
---|
1195 | should only be used internally by ExifTool. See
|
---|
1196 | L<Image::ExifTool::TagNames|Image::ExifTool::TagNames>, for a list of tag
|
---|
1197 | names indicating 'unsafe' and 'protected' tags. Default is 0.
|
---|
1198 |
|
---|
1199 | =item Replace
|
---|
1200 |
|
---|
1201 | Flag to replace the previous new values for this tag (ie. replace the values
|
---|
1202 | set in previous calls to L</SetNewValue>). This option is most commonly
|
---|
1203 | used to replace previously-set new values for List-type tags. Valid values
|
---|
1204 | are 0 (set new value normally -- adds to new values for List-type tags), 1
|
---|
1205 | (reset previous new values for this tag and replace with the specified new
|
---|
1206 | value) or 2 (reset previous new values only).
|
---|
1207 |
|
---|
1208 | =item Shift
|
---|
1209 |
|
---|
1210 | Shift the tag by the specified value. Currently only date/time tags can be
|
---|
1211 | shifted. Undefined for no shift, 1 for a positive shift, or -1 for a
|
---|
1212 | negative shift. If 0, the shift is applied only if the tag is shiftable,
|
---|
1213 | and the shift is positive if AddValue is set, or negative if DelValue is
|
---|
1214 | set. Default is undef. See
|
---|
1215 | L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl> for more information.
|
---|
1216 |
|
---|
1217 | =item Type
|
---|
1218 |
|
---|
1219 | The type of value being set. Valid values are PrintConv, ValueConv or Raw.
|
---|
1220 | Default is PrintConv if the L</PrintConv> Option is set, otherwise
|
---|
1221 | ValueConv.
|
---|
1222 |
|
---|
1223 | =back
|
---|
1224 |
|
---|
1225 | =item Return Values:
|
---|
1226 |
|
---|
1227 | In scalar context, returns the number of tags set and error messages are
|
---|
1228 | printed to STDERR. In list context, returns the number of tags set and the
|
---|
1229 | error string.
|
---|
1230 |
|
---|
1231 | =item Notes:
|
---|
1232 |
|
---|
1233 | When deleting groups of tags, the Replace option may be used as in the last
|
---|
1234 | example above to exclude specific groups from a mass delete. However, this
|
---|
1235 | technique may not be used to exclude individual tags. Instead, use
|
---|
1236 | L</SetNewValuesFromFile> to recover the values of individual tags after
|
---|
1237 | deleting a group.
|
---|
1238 |
|
---|
1239 | =back
|
---|
1240 |
|
---|
1241 | The following ExifTool options are effective in the call to L</SetNewValue>:
|
---|
1242 |
|
---|
1243 | Charset, Escape, IgnoreMinorErrors, Lang, ListSep, ListSplit, PrintConv and
|
---|
1244 | Verbose.
|
---|
1245 |
|
---|
1246 | =head2 SetNewValuesFromFile
|
---|
1247 |
|
---|
1248 | A very powerful routine that sets new values for tags from information found
|
---|
1249 | in a specified file.
|
---|
1250 |
|
---|
1251 | # set new values from all information in a file...
|
---|
1252 | my $info = $exifTool->SetNewValuesFromFile($srcFile);
|
---|
1253 | # ...then write these values to another image
|
---|
1254 | my $result = $exifTool->WriteInfo($file2, $outFile);
|
---|
1255 |
|
---|
1256 | # set all new values, preserving original groups
|
---|
1257 | $exifTool->SetNewValuesFromFile($srcFile, '*:*');
|
---|
1258 |
|
---|
1259 | # set specific information
|
---|
1260 | $exifTool->SetNewValuesFromFile($srcFile, @tags);
|
---|
1261 |
|
---|
1262 | # set new value from a different tag in specific group
|
---|
1263 | $exifTool->SetNewValuesFromFile($fp, 'IPTC:Keywords>XMP-dc:Subject');
|
---|
1264 |
|
---|
1265 | # add all IPTC keywords to XMP subject list
|
---|
1266 | $exifTool->SetNewValuesFromFile($fp, 'IPTC:Keywords+>XMP-dc:Subject');
|
---|
1267 |
|
---|
1268 | # set new value from an expression involving other tags
|
---|
1269 | $exifTool->SetNewValuesFromFile($file,
|
---|
1270 | 'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
|
---|
1271 |
|
---|
1272 | # set keywords list from the values of multiple tags
|
---|
1273 | $exifTool->SetNewValuesFromFile($file, { Replace => 0 },
|
---|
1274 | 'keywords<xmp:subject', 'keywords<filename');
|
---|
1275 |
|
---|
1276 | # copy all EXIF information, preserving the original IFD
|
---|
1277 | # (without '>*.*' tags would be copied to the preferred EXIF IFD)
|
---|
1278 | $exifTool->SetNewValuesFromFile($file, 'EXIF:*>*:*');
|
---|
1279 |
|
---|
1280 | =over 4
|
---|
1281 |
|
---|
1282 | =item Inputs:
|
---|
1283 |
|
---|
1284 | 0) ExifTool object reference
|
---|
1285 |
|
---|
1286 | 1) File name, file reference, or scalar reference
|
---|
1287 |
|
---|
1288 | 2-N) [optional] List of tag names to set or options hash references. All
|
---|
1289 | writable tags are set if none are specified. The tag names are not case
|
---|
1290 | sensitive, and may be prefixed by an optional family 0 or 1 group name,
|
---|
1291 | separated by a colon (ie. 'exif:iso'). A leading '-' indicates tags to be
|
---|
1292 | excluded (ie. '-comment'), or a trailing '#' causes the ValueConv value to
|
---|
1293 | be copied (same as setting the Type option to 'ValueConv' for this tag
|
---|
1294 | only). An asterisk ('*') may be used for the tag name, and is useful when a
|
---|
1295 | group is specified to set all tags from a group (ie. 'XMP:*'). A special
|
---|
1296 | feature allows tag names of the form 'SRCTAG>DSTTAG' (or
|
---|
1297 | 'DSTTAGE<lt>SRCTAG') to be specified to copy information to a tag with a
|
---|
1298 | different name or a specified group. Both 'SRCTAG' and 'DSTTAG' may use '*'
|
---|
1299 | and/or be prefixed by a group name (ie. 'modifyDate>fileModifyDate' or
|
---|
1300 | '*>xmp:*'). Copied tags may also be added or deleted from a list with
|
---|
1301 | arguments of the form 'SRCTAG+>DSTTAG' or 'SRCTAG->DSTTAG'. Tags are
|
---|
1302 | evaluated in order, so exclusions apply only to tags included earlier in the
|
---|
1303 | list. An extension of this feature allows the tag value to be set from an
|
---|
1304 | expression containing tag names with leading '$' symbols (ie.
|
---|
1305 | 'CommentE<lt>the file is $filename'). Braces '{}' may be used around the tag
|
---|
1306 | name to separate it from subsequent text, and a '$$' is used to to represent
|
---|
1307 | a '$' symbol. (The behaviour for missing tags in expressions is defined by
|
---|
1308 | the L</MissingTagValue> option.) Multiple options hash references may be
|
---|
1309 | passed to set different options for different tags. Options apply to
|
---|
1310 | subsequent tags in the argument list.
|
---|
1311 |
|
---|
1312 | By default, this routine will commute information between same-named tags in
|
---|
1313 | different groups, allowing information to be translated between images with
|
---|
1314 | different formats. This behaviour may be modified by specifying a group
|
---|
1315 | name for extracted tags (even if '*' is used as a group name), in which case
|
---|
1316 | the information is written to the original group, unless redirected to a
|
---|
1317 | different group. When '*' is used for a group name, the family 1 group of
|
---|
1318 | the original tag is preserved. (For example, specifying '*:*' copies all
|
---|
1319 | information while preserving the original family 1 groups.)
|
---|
1320 |
|
---|
1321 | =item SetNewValuesFromFile Options:
|
---|
1322 |
|
---|
1323 | The options are the same was for L</SetNewValue>, and are passed directly
|
---|
1324 | to L</SetNewValue> internally, with a few exceptions:
|
---|
1325 |
|
---|
1326 | - The Replace option defaults to 1 instead of 0 as with L</SetNewValue>.
|
---|
1327 |
|
---|
1328 | - The AddValue or DelValue option is set for individual tags if '+>' or '->'
|
---|
1329 | (or '+E<lt>' or '-E<lt>') are used.
|
---|
1330 |
|
---|
1331 | - The Group option is set for tags where a group name is given.
|
---|
1332 |
|
---|
1333 | - The Protected flag is set to 1 for individually specified tags.
|
---|
1334 |
|
---|
1335 | - The Type option also applies to extracted tags.
|
---|
1336 |
|
---|
1337 | =item Return Values:
|
---|
1338 |
|
---|
1339 | A hash of information that was set successfully. May include Warning or
|
---|
1340 | Error entries if there were problems reading the input file.
|
---|
1341 |
|
---|
1342 | =item Notes:
|
---|
1343 |
|
---|
1344 | The PrintConv option applies to this routine, but it normally should be left
|
---|
1345 | on to provide more reliable transfer of information between groups.
|
---|
1346 |
|
---|
1347 | If a preview image exists, it is not copied. The preview image must be
|
---|
1348 | transferred separately if desired, in a separate call to L</WriteInfo>
|
---|
1349 |
|
---|
1350 | When simply copying all information between files of the same type, it is
|
---|
1351 | usually desirable to preserve the original groups by specifying '*:*' for
|
---|
1352 | the tags to set.
|
---|
1353 |
|
---|
1354 | The L</Duplicates> option is always in effect for tags extracted from the
|
---|
1355 | source file using this routine.
|
---|
1356 |
|
---|
1357 | The L</Struct> option is enabled by default for tags extracted by this
|
---|
1358 | routine. This allows the hierarchy of complex structures to be preserved
|
---|
1359 | when copying, but the Struct option may be set to 0 to override this
|
---|
1360 | behaviour and copy as flattened tags instead.
|
---|
1361 |
|
---|
1362 | =back
|
---|
1363 |
|
---|
1364 | =head2 GetNewValues
|
---|
1365 |
|
---|
1366 | Get list of new Raw values for the specified tag. These are the values
|
---|
1367 | that will be written to file. Only tags which support a 'List' may return
|
---|
1368 | more than one value.
|
---|
1369 |
|
---|
1370 | $rawVal = $exifTool->GetNewValues($tag);
|
---|
1371 |
|
---|
1372 | @rawVals = $exifTool->GetNewValues($tag);
|
---|
1373 |
|
---|
1374 | =over 4
|
---|
1375 |
|
---|
1376 | =item Inputs:
|
---|
1377 |
|
---|
1378 | 0) ExifTool object reference
|
---|
1379 |
|
---|
1380 | 1) Tag name (case sensitive, may be prefixed by family 0 or 1 group name)
|
---|
1381 |
|
---|
1382 | =item Return Values:
|
---|
1383 |
|
---|
1384 | List of new Raw tag values, or first value in list when called in scalar
|
---|
1385 | context. The list may be empty either if the tag isn't being written, or if
|
---|
1386 | it is being deleted (ie. if L</SetNewValue> was called without a value).
|
---|
1387 |
|
---|
1388 | =back
|
---|
1389 |
|
---|
1390 | =head2 CountNewValues
|
---|
1391 |
|
---|
1392 | Return the total number of new values set.
|
---|
1393 |
|
---|
1394 | $numSet = $exifTool->CountNewValues();
|
---|
1395 | ($numSet, $numPseudo) = $exifTool->CountNewValues();
|
---|
1396 |
|
---|
1397 | =over 4
|
---|
1398 |
|
---|
1399 | =item Inputs:
|
---|
1400 |
|
---|
1401 | 0) ExifTool object reference
|
---|
1402 |
|
---|
1403 | =item Return Values:
|
---|
1404 |
|
---|
1405 | In scalar context, returns the total number of tags with new values set. In
|
---|
1406 | list context, also returns the number of "pseudo" tag values which have been
|
---|
1407 | set. "Pseudo" tags are tags like FileName and FileModifyDate which are not
|
---|
1408 | contained within the file and can be changed without rewriting the file.
|
---|
1409 |
|
---|
1410 | =back
|
---|
1411 |
|
---|
1412 | =head2 SaveNewValues
|
---|
1413 |
|
---|
1414 | Save state of new values to be later restored by L</RestoreNewValues>.
|
---|
1415 |
|
---|
1416 | $exifTool->SaveNewValues(); # save state of new values
|
---|
1417 | $exifTool->SetNewValue(ISO => 100); # set new value for ISO
|
---|
1418 | $exifTool->WriteInfo($src, $dst1); # write ISO + previous new values
|
---|
1419 | $exifTool->RestoreNewValues(); # restore previous new values
|
---|
1420 | $exifTool->WriteInfo($src, $dst2); # write previous new values only
|
---|
1421 |
|
---|
1422 | =over 4
|
---|
1423 |
|
---|
1424 | =item Inputs:
|
---|
1425 |
|
---|
1426 | 0) ExifTool object reference
|
---|
1427 |
|
---|
1428 | =item Return Value:
|
---|
1429 |
|
---|
1430 | None.
|
---|
1431 |
|
---|
1432 | =back
|
---|
1433 |
|
---|
1434 | =head2 RestoreNewValues
|
---|
1435 |
|
---|
1436 | Restore new values to the settings that existed when L</SaveNewValues> was
|
---|
1437 | last called. May be called repeatedly after a single call to
|
---|
1438 | L</SaveNewValues>. See L</SaveNewValues> above for an example.
|
---|
1439 |
|
---|
1440 | =over 4
|
---|
1441 |
|
---|
1442 | =item Inputs:
|
---|
1443 |
|
---|
1444 | 0) ExifTool object reference
|
---|
1445 |
|
---|
1446 | =item Return Value:
|
---|
1447 |
|
---|
1448 | None.
|
---|
1449 |
|
---|
1450 | =back
|
---|
1451 |
|
---|
1452 | =head2 SetFileModifyDate
|
---|
1453 |
|
---|
1454 | Set the file modification time from the new value of the FileModifyDate tag.
|
---|
1455 |
|
---|
1456 | $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00',
|
---|
1457 | Protected => 1);
|
---|
1458 | $result = $exifTool->SetFileModifyDate($file);
|
---|
1459 |
|
---|
1460 | =over 4
|
---|
1461 |
|
---|
1462 | =item Inputs:
|
---|
1463 |
|
---|
1464 | 0) ExifTool object reference
|
---|
1465 |
|
---|
1466 | 1) File name
|
---|
1467 |
|
---|
1468 | 2) [optional] Base time if applying shift (days before $^T)
|
---|
1469 |
|
---|
1470 | =item Return Value:
|
---|
1471 |
|
---|
1472 | 1 if the time was changed, 0 if nothing was done, or -1 if there was an
|
---|
1473 | error setting the time.
|
---|
1474 |
|
---|
1475 | =item Notes:
|
---|
1476 |
|
---|
1477 | Equivalent to, but more efficient than calling L</WriteInfo> when only the
|
---|
1478 | FileModifyDate tag has been set. If a timezone is not specified in the
|
---|
1479 | FileModifyDate value, local time is assumed. When shifting FileModifyDate,
|
---|
1480 | the time of the original file is used unless an optional base time is
|
---|
1481 | specified.
|
---|
1482 |
|
---|
1483 | =back
|
---|
1484 |
|
---|
1485 | =head2 SetFileName
|
---|
1486 |
|
---|
1487 | Set the file name and directory. If not specified, the new file name is
|
---|
1488 | derived from the new values of the FileName and Directory tags. If the
|
---|
1489 | FileName tag contains a '/', then the file is renamed into a new directory.
|
---|
1490 | If FileName ends with '/', then it is taken as a directory name and the file
|
---|
1491 | is moved into the new directory. The new value for the Directory tag takes
|
---|
1492 | precedence over any directory specified in FileName.
|
---|
1493 |
|
---|
1494 | $result = $exifTool->SetFileName($file);
|
---|
1495 | $result = $exifTool->SetFileName($file, $newName);
|
---|
1496 |
|
---|
1497 | =over 4
|
---|
1498 |
|
---|
1499 | =item Inputs:
|
---|
1500 |
|
---|
1501 | 0) ExifTool object reference
|
---|
1502 |
|
---|
1503 | 1) Current file name
|
---|
1504 |
|
---|
1505 | 2) [optional] New file name
|
---|
1506 |
|
---|
1507 | =item Return Value:
|
---|
1508 |
|
---|
1509 | 1 if the file name or directory was changed, 0 if nothing was done, or -1 if
|
---|
1510 | there was an error renaming the file.
|
---|
1511 |
|
---|
1512 | =item Notes:
|
---|
1513 |
|
---|
1514 | Will not overwrite existing files. New directories are created as necessary.
|
---|
1515 |
|
---|
1516 | =back
|
---|
1517 |
|
---|
1518 | =head2 SetNewGroups
|
---|
1519 |
|
---|
1520 | Set the order of the preferred groups when adding new information. In
|
---|
1521 | subsequent calls to L</SetNewValue>, new information will be created in the
|
---|
1522 | first valid group of this list. This has an impact only if the group is not
|
---|
1523 | specified when calling L</SetNewValue> and if the tag name exists in more
|
---|
1524 | than one group. The default order is EXIF, IPTC then XMP. Any family 0
|
---|
1525 | group name may be used. Case is not significant.
|
---|
1526 |
|
---|
1527 | $exifTool->SetNewGroups('XMP','EXIF','IPTC');
|
---|
1528 |
|
---|
1529 | =over 4
|
---|
1530 |
|
---|
1531 | =item Inputs:
|
---|
1532 |
|
---|
1533 | 0) ExifTool object reference
|
---|
1534 |
|
---|
1535 | 1-N) Groups in order of priority. If no groups are specified, the priorities
|
---|
1536 | are reset to the defaults.
|
---|
1537 |
|
---|
1538 | =item Return Value:
|
---|
1539 |
|
---|
1540 | None.
|
---|
1541 |
|
---|
1542 | =back
|
---|
1543 |
|
---|
1544 | =head2 GetNewGroups
|
---|
1545 |
|
---|
1546 | Get current group priority list.
|
---|
1547 |
|
---|
1548 | @groups = $exifTool->GetNewGroups();
|
---|
1549 |
|
---|
1550 | =over 4
|
---|
1551 |
|
---|
1552 | =item Inputs:
|
---|
1553 |
|
---|
1554 | 0) ExifTool object reference
|
---|
1555 |
|
---|
1556 | =item Return Values:
|
---|
1557 |
|
---|
1558 | List of group names in order of write priority. Highest priority first.
|
---|
1559 |
|
---|
1560 | =back
|
---|
1561 |
|
---|
1562 | =head2 GetTagID
|
---|
1563 |
|
---|
1564 | Get the ID for the specified tag. The ID is the IFD tag number in EXIF
|
---|
1565 | information, the property name in XMP information, or the data offset in a
|
---|
1566 | binary data block. For some tags, such as Composite tags where there is no
|
---|
1567 | ID, an empty string is returned. In list context, also returns a language
|
---|
1568 | code for the tag if available and different from the default language (ie.
|
---|
1569 | with alternate language entries for XMP "lang-alt" tags).
|
---|
1570 |
|
---|
1571 | $id = $exifTool->GetTagID($tag);
|
---|
1572 | ($id, $lang) = $exifTool->GetTagID($tag);
|
---|
1573 |
|
---|
1574 | =over 4
|
---|
1575 |
|
---|
1576 | =item Inputs:
|
---|
1577 |
|
---|
1578 | 0) ExifTool object reference
|
---|
1579 |
|
---|
1580 | 1) Tag key
|
---|
1581 |
|
---|
1582 | =item Return Values:
|
---|
1583 |
|
---|
1584 | In scalar context, returns the tag ID or '' if there is no ID for this tag.
|
---|
1585 | In list context, returns the tag ID (or '') and the language code (or
|
---|
1586 | undef).
|
---|
1587 |
|
---|
1588 | =back
|
---|
1589 |
|
---|
1590 | =head2 GetDescription
|
---|
1591 |
|
---|
1592 | Get description for specified tag. This function will always return a
|
---|
1593 | defined value. In the case where the description doesn't exist, one is
|
---|
1594 | generated from the tag name.
|
---|
1595 |
|
---|
1596 | =over 4
|
---|
1597 |
|
---|
1598 | =item Inputs:
|
---|
1599 |
|
---|
1600 | 0) ExifTool object reference
|
---|
1601 |
|
---|
1602 | 1) Tag key
|
---|
1603 |
|
---|
1604 | =item Return Values:
|
---|
1605 |
|
---|
1606 | A description for the specified tag.
|
---|
1607 |
|
---|
1608 | =back
|
---|
1609 |
|
---|
1610 | =head2 GetGroup
|
---|
1611 |
|
---|
1612 | Get group name(s) for a specified tag.
|
---|
1613 |
|
---|
1614 | # return family 0 group name (ie. 'EXIF');
|
---|
1615 | $group = $exifTool->GetGroup($tag, 0);
|
---|
1616 |
|
---|
1617 | # return all groups (ie. qw{EXIF IFD0 Author Main})
|
---|
1618 | @groups = $exifTool->GetGroup($tag);
|
---|
1619 |
|
---|
1620 | # return groups as a string (ie. 'Main:IFD0:Author')
|
---|
1621 | $group = $exifTool->GetGroup($tag, ':3:1:2');
|
---|
1622 |
|
---|
1623 | # return groups as a simplified string (ie. 'IFD0:Author')
|
---|
1624 | $group = $exifTool->GetGroup($tag, '3:1:2');
|
---|
1625 |
|
---|
1626 | =over 4
|
---|
1627 |
|
---|
1628 | =item Inputs:
|
---|
1629 |
|
---|
1630 | 0) ExifTool object reference
|
---|
1631 |
|
---|
1632 | 1) Tag key
|
---|
1633 |
|
---|
1634 | 2) [optional] Group family number, or string of numbers separated by colons
|
---|
1635 |
|
---|
1636 | =item Return Values:
|
---|
1637 |
|
---|
1638 | Group name (or '' if tag has no group). If no group family is specified,
|
---|
1639 | L</GetGroup> returns the name of the group in family 0 when called in scalar
|
---|
1640 | context, or the names of groups for all families in list context. Returns a
|
---|
1641 | string of group names separated by colons if the input group family contains
|
---|
1642 | a colon. The string is simplified to remove a leading 'Main:' and adjacent
|
---|
1643 | identical group names unless the family string begins with a colon.
|
---|
1644 |
|
---|
1645 | =item Notes:
|
---|
1646 |
|
---|
1647 | The group family numbers are currently available:
|
---|
1648 |
|
---|
1649 | 0) Information Type (ie. EXIF, XMP, IPTC)
|
---|
1650 | 1) Specific Location (ie. IFD0, XMP-dc)
|
---|
1651 | 2) Category (ie. Author, Time)
|
---|
1652 | 3) Document Number (ie. Main, Doc1, Doc3-2)
|
---|
1653 | 4) Instance Number (ie. Copy1, Copy2, Copy3...)
|
---|
1654 |
|
---|
1655 | Families 0 and 1 are based on the file structure, and are similar except
|
---|
1656 | that family 1 is more specific and sub-divides some groups to give more
|
---|
1657 | detail about the specific location where the information was found. For
|
---|
1658 | example, the EXIF group is split up based on the specific IFD (Image File
|
---|
1659 | Directory), the MakerNotes group is divided into groups for each
|
---|
1660 | manufacturer, and the XMP group is separated based on the XMP namespace
|
---|
1661 | prefix. Note that only common XMP namespaces are listed in the
|
---|
1662 | L<GetAllGroups documentation|/GetAllGroups [static]>, but additional
|
---|
1663 | namespaces may be present in some XMP data. Also note that the 'XMP-xmp...'
|
---|
1664 | group names may appear in the older form 'XMP-xap...' since these names
|
---|
1665 | evolved as the XMP standard was developed. The ICC_Profile group is broken
|
---|
1666 | down to give information about the specific ICC_Profile tag from which
|
---|
1667 | multiple values were extracted. As well, information extracted from the
|
---|
1668 | ICC_Profile header is separated into the ICC-header group.
|
---|
1669 |
|
---|
1670 | Family 2 classifies information based on the logical category to which the
|
---|
1671 | information refers.
|
---|
1672 |
|
---|
1673 | Family 3 gives the document number for tags extracted from embedded
|
---|
1674 | documents, or 'Main' for tags from the main document. (See the
|
---|
1675 | L</ExtractEmbedded> option for extracting tags from embedded documents.)
|
---|
1676 | Nested sub-documents (if they exist) are indicated by numbers separated with
|
---|
1677 | dashes in the group name, to an arbitrary depth. (ie. 'Doc2-3-1' is the 1st
|
---|
1678 | sub-sub-document of the 3rd sub-document of the 2nd embedded document of the
|
---|
1679 | main file.)
|
---|
1680 |
|
---|
1681 | Family 4 provides a method for differentiating tags when multiple tags exist
|
---|
1682 | with the same name in the same location. The primary instance of a tag (the
|
---|
1683 | tag extracted when the Duplicates option is disabled and no group is
|
---|
1684 | specified) has no family 4 group name, but additional instances have have
|
---|
1685 | family 4 group names of 'Copy1', 'Copy2', 'Copy3', etc.
|
---|
1686 |
|
---|
1687 | See L</GetAllGroups [static]> for complete lists of group names.
|
---|
1688 |
|
---|
1689 | =back
|
---|
1690 |
|
---|
1691 | =head2 GetGroups
|
---|
1692 |
|
---|
1693 | Get list of group names that exist in the specified information.
|
---|
1694 |
|
---|
1695 | @groups = $exifTool->GetGroups($info, 2);
|
---|
1696 | @groups = $exifTool->GetGroups('3:1');
|
---|
1697 |
|
---|
1698 | =over 4
|
---|
1699 |
|
---|
1700 | =item Inputs:
|
---|
1701 |
|
---|
1702 | 0) ExifTool object reference
|
---|
1703 |
|
---|
1704 | 1) [optional] Info hash ref (default is all extracted info)
|
---|
1705 |
|
---|
1706 | 2) [optional] Group family number, or string of numbers (default 0)
|
---|
1707 |
|
---|
1708 | =item Return Values:
|
---|
1709 |
|
---|
1710 | List of group names in alphabetical order. If information hash is not
|
---|
1711 | specified, the group names are returned for all extracted information. See
|
---|
1712 | L</GetGroup> for an description of family numbers and family number strings.
|
---|
1713 |
|
---|
1714 | =back
|
---|
1715 |
|
---|
1716 | =head2 BuildCompositeTags
|
---|
1717 |
|
---|
1718 | Builds composite tags from required tags. The composite tags are
|
---|
1719 | convenience tags which are derived from the values of other tags. This
|
---|
1720 | routine is called automatically by L</ImageInfo> and L</ExtractInfo> if the
|
---|
1721 | Composite option is set.
|
---|
1722 |
|
---|
1723 | =over 4
|
---|
1724 |
|
---|
1725 | =item Inputs:
|
---|
1726 |
|
---|
1727 | 0) ExifTool object reference
|
---|
1728 |
|
---|
1729 | =item Return Values:
|
---|
1730 |
|
---|
1731 | (none)
|
---|
1732 |
|
---|
1733 | =item Notes:
|
---|
1734 |
|
---|
1735 | Tag values are calculated in alphabetical order unless a tag Require's or
|
---|
1736 | Desire's another composite tag, in which case the calculation is deferred
|
---|
1737 | until after the other tag is calculated. Composite tags may need to read
|
---|
1738 | data from the image for their value to be determined, so for these
|
---|
1739 | L</BuildCompositeTags> must be called while the image is available. This is
|
---|
1740 | only a problem if L</ImageInfo> is called with a filename (as opposed to a
|
---|
1741 | file reference or scalar reference) since in this case the file is closed
|
---|
1742 | before L</ImageInfo> returns. However if you enable the Composite option,
|
---|
1743 | L</BuildCompositeTags> is called from within L</ImageInfo> before the file
|
---|
1744 | is closed.
|
---|
1745 |
|
---|
1746 | =back
|
---|
1747 |
|
---|
1748 | =head2 GetTagName [static]
|
---|
1749 |
|
---|
1750 | Get name of tag from tag key. This is a convenience function that
|
---|
1751 | strips the embedded instance number, if it exists, from the tag key.
|
---|
1752 |
|
---|
1753 | Note: "static" in the heading above indicates that the function does not
|
---|
1754 | require an ExifTool object reference as the first argument. All functions
|
---|
1755 | documented below are also static.
|
---|
1756 |
|
---|
1757 | $tagName = Image::ExifTool::GetTagName($tag);
|
---|
1758 |
|
---|
1759 | =over 4
|
---|
1760 |
|
---|
1761 | =item Inputs:
|
---|
1762 |
|
---|
1763 | 0) Tag key
|
---|
1764 |
|
---|
1765 | =item Return Value:
|
---|
1766 |
|
---|
1767 | Tag name. This is the same as the tag key but has the instance number
|
---|
1768 | removed.
|
---|
1769 |
|
---|
1770 | =back
|
---|
1771 |
|
---|
1772 | =head2 GetShortcuts [static]
|
---|
1773 |
|
---|
1774 | Get a list of shortcut tags.
|
---|
1775 |
|
---|
1776 | =over 4
|
---|
1777 |
|
---|
1778 | =item Inputs:
|
---|
1779 |
|
---|
1780 | (none)
|
---|
1781 |
|
---|
1782 | =item Return Values:
|
---|
1783 |
|
---|
1784 | List of shortcut tags (as defined in Image::ExifTool::Shortcuts).
|
---|
1785 |
|
---|
1786 | =back
|
---|
1787 |
|
---|
1788 | =head2 GetAllTags [static]
|
---|
1789 |
|
---|
1790 | Get list of all available tag names.
|
---|
1791 |
|
---|
1792 | @tagList = Image::ExifTool::GetAllTags($group);
|
---|
1793 |
|
---|
1794 | =over 4
|
---|
1795 |
|
---|
1796 | =item Inputs:
|
---|
1797 |
|
---|
1798 | 0) [optional] Group name, or string of group names separated by colons
|
---|
1799 |
|
---|
1800 | =item Return Values:
|
---|
1801 |
|
---|
1802 | A list of all available tags in alphabetical order, or all tags in a
|
---|
1803 | specified group or intersection of groups. The group name is case
|
---|
1804 | insensitive, and any group in families 0-2 may be used except for EXIF
|
---|
1805 | family 1 groups (ie. the specific IFD).
|
---|
1806 |
|
---|
1807 | =back
|
---|
1808 |
|
---|
1809 | =head2 GetWritableTags [static]
|
---|
1810 |
|
---|
1811 | Get list of all writable tag names.
|
---|
1812 |
|
---|
1813 | @tagList = Image::ExifTool::GetWritableTags($group);
|
---|
1814 |
|
---|
1815 | =over 4
|
---|
1816 |
|
---|
1817 | =item Inputs:
|
---|
1818 |
|
---|
1819 | 0) [optional] Group name, or string of group names separated by colons
|
---|
1820 |
|
---|
1821 | =item Return Values:
|
---|
1822 |
|
---|
1823 | A list of all writable tags in alphabetical order. These are the tags for
|
---|
1824 | which values may be set through L</SetNewValue>. If a group name is given,
|
---|
1825 | returns only writable tags in specified group(s). The group name is case
|
---|
1826 | insensitive, and any group in families 0-2 may be used except for EXIF
|
---|
1827 | family 1 groups (ie. the specific IFD).
|
---|
1828 |
|
---|
1829 | =back
|
---|
1830 |
|
---|
1831 | =head2 GetAllGroups [static]
|
---|
1832 |
|
---|
1833 | Get list of all group names in specified family.
|
---|
1834 |
|
---|
1835 | @groupList = Image::ExifTool::GetAllGroups($family);
|
---|
1836 |
|
---|
1837 | =over 4
|
---|
1838 |
|
---|
1839 | =item Inputs:
|
---|
1840 |
|
---|
1841 | 0) Group family number (0-4)
|
---|
1842 |
|
---|
1843 | =item Return Values:
|
---|
1844 |
|
---|
1845 | A list of all groups in the specified family in alphabetical order.
|
---|
1846 |
|
---|
1847 | =back
|
---|
1848 |
|
---|
1849 | Here is a complete list of groups for each of these families:
|
---|
1850 |
|
---|
1851 | =over 4
|
---|
1852 |
|
---|
1853 | =item Family 0 (Information Type):
|
---|
1854 |
|
---|
1855 | AFCP, AIFF, APE, APP0, APP12, APP13, APP14, APP15, APP4, APP5, APP6, APP8,
|
---|
1856 | ASF, CanonVRD, Composite, DICOM, DNG, DV, DjVu, Ducky, EXE, EXIF, ExifTool,
|
---|
1857 | FLAC, File, Flash, FlashPix, Font, FotoStation, GIF, GIMP, GeoTiff, H264,
|
---|
1858 | HTML, ICC_Profile, ID3, IPTC, ITC, JFIF, JPEG, Jpeg2000, LNK, Leaf, M2TS,
|
---|
1859 | MIE, MIFF, MNG, MPC, MPEG, MPF, MXF, MakerNotes, Matroska, Meta, PDF, PICT,
|
---|
1860 | PNG, PSP, PhotoMechanic, Photoshop, PostScript, PrintIM, QuickTime, RAF,
|
---|
1861 | RIFF, RSRC, RTF, Rawzor, Real, SVG, SigmaRaw, Stim, Vorbis, XML, XMP, ZIP
|
---|
1862 |
|
---|
1863 | =item Family 1 (Specific Location):
|
---|
1864 |
|
---|
1865 | AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, CIFF, Canon, CanonCustom,
|
---|
1866 | CanonRaw, CanonVRD, Casio, Chapter#, Composite, DICOM, DNG, DV, DjVu,
|
---|
1867 | DjVu-Meta, Ducky, EPPIM, EXE, EXIF, ExifIFD, ExifTool, FLAC, File, Flash,
|
---|
1868 | FlashPix, Font, FotoStation, FujiFilm, GE, GIF, GIMP, GPS, GeoTiff,
|
---|
1869 | GlobParamIFD, GraphConv, H264, HP, HTML, HTML-dc, HTML-ncc, HTML-office,
|
---|
1870 | HTML-prod, HTML-vw96, HTTP-equiv, ICC-chrm, ICC-clrt, ICC-header, ICC-meas,
|
---|
1871 | ICC-meta, ICC-view, ICC_Profile, ICC_Profile#, ID3, ID3v1, ID3v1_Enh,
|
---|
1872 | ID3v2_2, ID3v2_3, ID3v2_4, IFD0, IFD1, IPTC, IPTC#, ITC, InteropIFD, JFIF,
|
---|
1873 | JPEG, JVC, Jpeg2000, KDC_IFD, Kodak, KodakBordersIFD, KodakEffectsIFD,
|
---|
1874 | KodakIFD, KyoceraRaw, LNK, Leaf, LeafSubIFD, Leica, M2TS, MAC, MIE-Audio,
|
---|
1875 | MIE-Camera, MIE-Canon, MIE-Doc, MIE-Extender, MIE-Flash, MIE-GPS, MIE-Geo,
|
---|
1876 | MIE-Image, MIE-Lens, MIE-Main, MIE-MakerNotes, MIE-Meta, MIE-Orient,
|
---|
1877 | MIE-Preview, MIE-Thumbnail, MIE-UTM, MIE-Unknown, MIE-Video, MIFF, MNG, MPC,
|
---|
1878 | MPEG, MPF0, MPImage, MXF, MakerNotes, MakerUnknown, Matroska, MetaIFD,
|
---|
1879 | Microsoft, Minolta, MinoltaRaw, NITF, Nikon, NikonCapture, NikonCustom,
|
---|
1880 | NikonScan, Olympus, PDF, PICT, PNG, PSP, Panasonic, Pentax, PhotoMechanic,
|
---|
1881 | Photoshop, PictureInfo, PostScript, PreviewIFD, PrintIM, ProfileIFD,
|
---|
1882 | QuickTime, RAF, RAF2, RIFF, RMETA, RSRC, RTF, Rawzor, Real, Real-CONT,
|
---|
1883 | Real-MDPR, Real-PROP, Real-RA3, Real-RA4, Real-RA5, Real-RJMD, Reconyx,
|
---|
1884 | Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD, SRF#, SVG, Samsung, Sanyo,
|
---|
1885 | Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim, SubIFD, System, Track#,
|
---|
1886 | Version0, Vorbis, XML, XMP, XMP-DICOM, XMP-MP, XMP-MP1, XMP-PixelLive,
|
---|
1887 | XMP-acdsee, XMP-album, XMP-aux, XMP-cc, XMP-cell, XMP-crs, XMP-dc, XMP-dex,
|
---|
1888 | XMP-digiKam, XMP-exif, XMP-iptcCore, XMP-iptcExt, XMP-lr, XMP-mediapro,
|
---|
1889 | XMP-microsoft, XMP-mwg-coll, XMP-mwg-kw, XMP-mwg-rs, XMP-pdf, XMP-pdfx,
|
---|
1890 | XMP-photomech, XMP-photoshop, XMP-plus, XMP-prism, XMP-prl, XMP-pur,
|
---|
1891 | XMP-rdf, XMP-swf, XMP-tiff, XMP-x, XMP-xmp, XMP-xmpBJ, XMP-xmpDM, XMP-xmpMM,
|
---|
1892 | XMP-xmpNote, XMP-xmpPLUS, XMP-xmpRights, XMP-xmpTPg, ZIP
|
---|
1893 |
|
---|
1894 | =item Family 2 (Category):
|
---|
1895 |
|
---|
1896 | Audio, Author, Camera, Document, ExifTool, Image, Location, Other, Printing,
|
---|
1897 | Time, Unknown, Video
|
---|
1898 |
|
---|
1899 | =item Family 3 (Document Number):
|
---|
1900 |
|
---|
1901 | Doc#, Main
|
---|
1902 |
|
---|
1903 | =item Family 4 (Instance Number):
|
---|
1904 |
|
---|
1905 | Copy#
|
---|
1906 |
|
---|
1907 | =back
|
---|
1908 |
|
---|
1909 | =head2 GetDeleteGroups [static]
|
---|
1910 |
|
---|
1911 | Get list of all deletable group names.
|
---|
1912 |
|
---|
1913 | @delGroups = Image::ExifTool::GetDeleteGroups();
|
---|
1914 |
|
---|
1915 | =over 4
|
---|
1916 |
|
---|
1917 | =item Inputs:
|
---|
1918 |
|
---|
1919 | None.
|
---|
1920 |
|
---|
1921 | =item Return Values:
|
---|
1922 |
|
---|
1923 | A list of deletable group names in alphabetical order. The current list of
|
---|
1924 | deletable group names is:
|
---|
1925 |
|
---|
1926 | AFCP, CIFF, CanonVRD, EXIF, ExifIFD, Ducky, File, FlashPix, FotoStation,
|
---|
1927 | GlobParamIFD, GPS, IFD0, IFD1, InteropIFD, ICC_Profile, IPTC, JFIF,
|
---|
1928 | MakerNotes, Meta, MetaIFD, MIE, PhotoMechanic, Photoshop, PNG, PrintIM,
|
---|
1929 | RMETA, SubIFD, Trailer, XMP
|
---|
1930 |
|
---|
1931 | All names in this list are either family 0 or family 1 group names, with the
|
---|
1932 | exception of 'Trailer' which allows all trailers in JPEG and TIFF-format
|
---|
1933 | images to be deleted at once, including unknown trailers. To schedule a
|
---|
1934 | group for deletion, call L</SetNewValue> with an undefined value and a tag
|
---|
1935 | name like 'Trailer:*'.
|
---|
1936 |
|
---|
1937 | =back
|
---|
1938 |
|
---|
1939 | =head2 GetFileType [static]
|
---|
1940 |
|
---|
1941 | Get type of file given file name.
|
---|
1942 |
|
---|
1943 | my $type = Image::ExifTool::GetFileType($filename);
|
---|
1944 | my $desc = Image::ExifTool::GetFileType($filename, 1);
|
---|
1945 |
|
---|
1946 | =over 4
|
---|
1947 |
|
---|
1948 | =item Inputs:
|
---|
1949 |
|
---|
1950 | 0) [optional] File name (or just an extension)
|
---|
1951 |
|
---|
1952 | 1) [optional] Flag to return a description instead of a type. Set to 0 to
|
---|
1953 | return type for recognized but unsupported files (otherwise the return value
|
---|
1954 | for unsupported files is undef).
|
---|
1955 |
|
---|
1956 | =item Return Value:
|
---|
1957 |
|
---|
1958 | A string, based on the file extension, which indicates the basic format of
|
---|
1959 | the file. Note that some files may be based on other formats (like many RAW
|
---|
1960 | image formats are based on TIFF). In array context, may return more than
|
---|
1961 | one file type if the file may be based on different formats. Returns undef
|
---|
1962 | if files with this extension are not yet supported by ExifTool. Returns a
|
---|
1963 | list of extensions for all supported file types if no input extension is
|
---|
1964 | specified (or all recognized file types if the description flag is set to 0).
|
---|
1965 | Returns a more detailed description of the specific file format when the
|
---|
1966 | description flag is set.
|
---|
1967 |
|
---|
1968 | =back
|
---|
1969 |
|
---|
1970 | =head2 CanWrite [static]
|
---|
1971 |
|
---|
1972 | Can the specified file be written?
|
---|
1973 |
|
---|
1974 | my $writable = Image::ExifTool::CanWrite($filename);
|
---|
1975 |
|
---|
1976 | =over 4
|
---|
1977 |
|
---|
1978 | =item Inputs:
|
---|
1979 |
|
---|
1980 | 0) File name or extension
|
---|
1981 |
|
---|
1982 | =item Return Value:
|
---|
1983 |
|
---|
1984 | True if ExifTool supports writing files of this type (based on the file
|
---|
1985 | extension).
|
---|
1986 |
|
---|
1987 | =back
|
---|
1988 |
|
---|
1989 | =head2 CanCreate [static]
|
---|
1990 |
|
---|
1991 | Can the specified file be created?
|
---|
1992 |
|
---|
1993 | my $creatable = Image::ExifTool::CanCreate($filename);
|
---|
1994 |
|
---|
1995 | =over 4
|
---|
1996 |
|
---|
1997 | =item Inputs:
|
---|
1998 |
|
---|
1999 | 0) File name or extension
|
---|
2000 |
|
---|
2001 | =item Return Value:
|
---|
2002 |
|
---|
2003 | True if ExifTool can create files with this extension from scratch.
|
---|
2004 | Currently, this can only be done with XMP, MIE, ICC, VRD and EXIF files.
|
---|
2005 |
|
---|
2006 | =back
|
---|
2007 |
|
---|
2008 | =head1 CHARACTER ENCODINGS
|
---|
2009 |
|
---|
2010 | Certain meta information formats allow coded character sets other than plain
|
---|
2011 | ASCII. When reading, 8-bit encodings are passed straight through ExifTool
|
---|
2012 | without re-coding unless specified otherwise below, and multi-byte encodings
|
---|
2013 | are converted according to the L</Charset> option ('UTF8' by default). When
|
---|
2014 | writing, the inverse conversions are performed. See the L</Charset> option
|
---|
2015 | for a list of valid character sets.
|
---|
2016 |
|
---|
2017 | More specific details are given below about how character coding is handled
|
---|
2018 | for EXIF, IPTC, XMP, PNG, ID3, PDF and MIE information:
|
---|
2019 |
|
---|
2020 | =head2 EXIF
|
---|
2021 |
|
---|
2022 | Most textual information in EXIF is stored in ASCII format, and ExifTool
|
---|
2023 | does not convert these tags. However it is not uncommon for applications to
|
---|
2024 | write UTF-8 or other encodings where ASCII is expected, and ExifTool will
|
---|
2025 | quite happily read/write any encoding without conversion. For a few EXIF
|
---|
2026 | tags (UserComment, GPSProcessingMethod and GPSAreaInformation) the stored
|
---|
2027 | text may be encoded either in ASCII, Unicode (UCS-2) or JIS. When reading
|
---|
2028 | these tags, Unicode and JIS are converted to the character set specified by
|
---|
2029 | the L</Charset> option. Other encodings are not converted. When writing,
|
---|
2030 | text is stored as ASCII unless the string contains special characters, in
|
---|
2031 | which case it is converted from the specified character set and stored as
|
---|
2032 | Unicode. ExifTool writes Unicode in native EXIF byte ordering by default,
|
---|
2033 | but this may be changed by setting the ExifUnicodeByteOrder tag. The EXIF
|
---|
2034 | "XP" tags (XPTitle, XPComment, etc) are always stored as little-endian
|
---|
2035 | Unicode, and are read and written using the specified character set.
|
---|
2036 |
|
---|
2037 | =head2 IPTC
|
---|
2038 |
|
---|
2039 | The value of the IPTC:CodedCharacterSet tag determines how the internal IPTC
|
---|
2040 | string values are interpreted. If CodedCharacterSet exists and has a value
|
---|
2041 | of 'UTF8' (or 'ESC % G') then string values are assumed to be stored as
|
---|
2042 | UTF-8, otherwise Windows Latin1 (cp1252, 'Latin') coding is assumed by
|
---|
2043 | default, but this can be changed with the L</CharsetIPTC> option. When
|
---|
2044 | reading, these strings are converted to the character set specified by the
|
---|
2045 | L</Charset> option. When writing, the inverse conversions are performed.
|
---|
2046 | No conversion is done if the internal (IPTC) and external (ExifTool)
|
---|
2047 | character sets are the same. Note that ISO 2022 character set shifting is
|
---|
2048 | not supported. Instead, a warning is issued and the string is not converted
|
---|
2049 | if an ISO 2022 shift code is found. See L<http://www.iptc.org/IIM/> for the
|
---|
2050 | official IPTC specification.
|
---|
2051 |
|
---|
2052 | =head2 XMP
|
---|
2053 |
|
---|
2054 | Exiftool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts them all
|
---|
2055 | to UTF-8 internally. Also, all XML character entity references and numeric
|
---|
2056 | character references are converted. When writing, ExifTool always encodes
|
---|
2057 | XMP as UTF-8, converting the following 5 characters to XML character
|
---|
2058 | references: E<amp> E<lt> E<gt> E<39> E<quot>. By default no further
|
---|
2059 | conversion is performed, however if the L</Charset> option is other than
|
---|
2060 | 'UTF8' then text is converted to/from a specified character set when
|
---|
2061 | reading/writing.
|
---|
2062 |
|
---|
2063 | =head2 PNG
|
---|
2064 |
|
---|
2065 | L<PNG TextualData tags|Image::ExifTool::TagNames/"PNG TextualData Tags"> are
|
---|
2066 | stored as tEXt, zTXt and iTXt chunks in PNG images. The tEXt and zTXt
|
---|
2067 | chunks use ISO 8859-1 encoding, while iTXt uses UTF-8. When reading,
|
---|
2068 | ExifTool converts all PNG textual data to the character set specified by the
|
---|
2069 | L</Charset> option. When writing, ExifTool generates a tEXt chunk (or zTXt
|
---|
2070 | with the L</Compress> option) if the text doesn't contain special characters
|
---|
2071 | or if Latin encoding is specified; otherwise an iTXt chunk is used and the
|
---|
2072 | text is converted from the specified character set and stored as UTF-8.
|
---|
2073 |
|
---|
2074 | =head2 ID3
|
---|
2075 |
|
---|
2076 | The ID3v1 specification officially supports only ISO 8859-1 encoding (a
|
---|
2077 | subset of Windows Latin1), although some applications may incorrectly use
|
---|
2078 | other character sets. By default ExifTool converts ID3v1 text from Latin to
|
---|
2079 | the character set specified by the </Charset> option. However, the internal
|
---|
2080 | ID3v1 charset may be specified with the L</CharsetID3> option. The encoding
|
---|
2081 | for ID3v2 information is stored in the file, so ExifTool converts ID3v2 text
|
---|
2082 | from this encoding to the character set specified by the L</Charset> option.
|
---|
2083 | ExifTool does not currently write ID3 information.
|
---|
2084 |
|
---|
2085 | =head2 PDF
|
---|
2086 |
|
---|
2087 | PDF text strings are stored in either PDFDocEncoding (similar to Windows
|
---|
2088 | Latin1) or Unicode (UCS-2). When reading, ExifTool converts to the
|
---|
2089 | character set specified by the L</Charset> option. When writing, ExifTool
|
---|
2090 | encodes input text from the specified character set as Unicode only if the
|
---|
2091 | string contains special characters, otherwise PDFDocEncoding is used.
|
---|
2092 |
|
---|
2093 | =head2 MIE
|
---|
2094 |
|
---|
2095 | MIE strings are stored as either UTF-8 or ISO 8859-1. When reading, UTF-8
|
---|
2096 | strings are converted according to the L</Charset> option, and ISO 8859-1
|
---|
2097 | strings are never converted. When writing, input strings are converted from
|
---|
2098 | the specified character set to UTF-8. The resulting strings are stored as
|
---|
2099 | UTF-8 if they contain multi-byte UTF-8 character sequences, otherwise they
|
---|
2100 | are stored as ISO 8859-1.
|
---|
2101 |
|
---|
2102 | =head1 AUTHOR
|
---|
2103 |
|
---|
2104 | Copyright 2003-2011, Phil Harvey
|
---|
2105 |
|
---|
2106 | This library is free software; you can redistribute it and/or modify it
|
---|
2107 | under the same terms as Perl itself.
|
---|
2108 |
|
---|
2109 | =head1 ACKNOWLEDGEMENTS
|
---|
2110 |
|
---|
2111 | Many people have helped in the development of ExifTool through their bug
|
---|
2112 | reports, comments and suggestions, and/or additions to the code. See the
|
---|
2113 | ACKNOWLEDGEMENTS in the individual Image::ExifTool modules and in
|
---|
2114 | html/index.html of the Image::ExifTool distribution package for a list of
|
---|
2115 | people who have contributed to this project.
|
---|
2116 |
|
---|
2117 | =head1 SEE ALSO
|
---|
2118 |
|
---|
2119 | L<exiftool(1)|exiftool>,
|
---|
2120 | L<Image::ExifTool::TagNames(3pm)|Image::ExifTool::TagNames>,
|
---|
2121 | L<Image::ExifTool::Shortcuts(3pm)|Image::ExifTool::Shortcuts>,
|
---|
2122 | L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl>,
|
---|
2123 | L<Image::Info(3pm)|Image::Info>,
|
---|
2124 | L<Image::MetaData::JPEG(3pm)|Image::MetaData::JPEG>
|
---|
2125 |
|
---|
2126 | =cut
|
---|
2127 |
|
---|
2128 | # end
|
---|