#------------------------------------------------------------------------------
# File:         ExifTool.pod - Documentation for File::ExifTool
#
# Description:  Utility to read EXIF information from image files
#
# URL:          http://owl.phy.queensu.ca/~phil/exiftool/
#
# Legal:        Copyright (c) 2003-2004 Phil Harvey (phil@owl.phy.queensu.ca)
#               This library is free software; you can redistribute it and/or
#               modify it under the same terms as Perl itself.
#------------------------------------------------------------------------------

=head1 NAME

Image::ExifTool - Extract meta information from image files

=head1 SYNOPSIS

  use Image::ExifTool 'ImageInfo';

  # Get hash of tag names/values for all image meta data (procedural)
  $info = ImageInfo('a.jpg');

  # Create a new Image::ExifTool object
  $exifTool = new Image::ExifTool;

  # Get hash reference for all meta information in an image (object oriented)
  $info = $exifTool->ImageInfo($file, \%options, \@tagList, $tag, ...);

  # Set options
  $oldValue = $exifTool->Options(Option => 'Value', ...);

  # Reset options
  $exifTool->ClearOptions();

  # Extract meta information from an image
  $success = $exifTool->ExtractInfo($file, \%options, \@tagList, ...);

  # Get hash reference to extracted meta information
  $info = $exifTool->GetInfo(\%options, \@tagList, $tag, ...);

  # Combine meta information hashes
  $combined = $exifTool->CombineInfo($info1, $info2, ...);

  # Get list of tag names from information hash
  @tagList = $exifTool->GetTagList($info, $sortOrder);

  # Get list of all tags found in image
  @foundTags = $exifTool->GetFoundTags($sortOrder);

  # Get list of tags requested to be extracted from image
  @requestedTags = $exifTool->GetRequestedTags();

  # Get the data value of a specified tag
  $value = $exifTool->GetValue($tag, $type);

  # Get the description of a tag
  $description = $exifTool->GetDescription($tag);

  # Get the name of the group associated with this tag
  $group = $exifTool->GetGroup($tag, $family);

  # Get a list of all groups associated with the specified information
  @groups = $exifTool->GetGroups($info, $family);

  # Calculate tags which are derived from the values of other tags
  $exifTool->BuildCompositeTags();

  # Get the name of this tag
  $tagName = Image::ExifTool::GetTagName($tag);

  # Get a list of shortcut tag names
  @shortcuts = Image::ExifTool::GetShortcuts();

  # Get a list of all available tag names
  @allTags = Image::ExifTool::GetAllTags();

  # Get a list of all available group names
  @allGroups = Image::ExifTool::GetAllGroups($family);

=head1 DESCRIPTION

ExifTool provides an extensible set of perl modules to extract and parse
EXIF, IPTC, XMP and GeoTIFF meta information from JPEG, TIFF, GIF, THM, CRW
(Canon RAW), CR2 (Canon 1D Mk II RAW), NEF (Nikon Electronic image Format)
and DNG (Digital Negative) images.  ExifTool currently reads the maker notes
of images from Canon, Casio, FujiFilm, Minolta, Nikon, Olympus, Pentax,
Sanyo and Sigma digital cameras.

=head1 METHODS

=head2 new

Creates a new ExifTool object.

    $exifTool = new Image::ExifTool;

=head2 ImageInfo

Obtain meta information from image.  This is the one step function for
obtaining meta information from an image.  Internally, B<ImageInfo> calls
B<ExtractInfo> to extract the information, B<GetInfo> to generate the
information hash, and B<GetTagList> for the returned tag list.

    # Return meta information for 2 tags only
    $info = ImageInfo($filename, $tag1, $tag2)

    # Return information about an open image file
    $info = $exifTool->ImageInfo(\*FILE)

    # Return information from image data in memory for specified tags
    $info = ImageInfo(\$imageData, \@tagList, \%options)

=over 4

=item Inputs:

B<ImageInfo> is very flexible about the input arguments, and interprets
them based on their type.  It may be called with one or more arguments.
The one required argument is either a SCALAR (the image file name), a GLOB
reference (a reference to the image file) or a SCALAR reference (a
reference to the image in memory).  Other arguments are optional.  The
order of the arguments is not significant, except that the first SCALAR is
taken to be the file name unless a file reference or scalar reference came
earlier in the argument list.

Below is an explanation of how the B<ImageInfo> function arguments are
interpreted:

=over 4

=item ExifTool ref

B<ImageInfo> may be called with an ExifTool object if desired.  The
advantage of using the object-oriented form is that the options may be set
before calling B<ImageInfo>, and the object may be used afterward to access
member functions.

=item SCALAR

The first scalar argument is taken to be the file name unless an earlier
argument specified the image data via a file reference (GLOB ref) or data
reference (SCALAR ref). The remaining scalar arguments are names of tags for
requested information.  If no tags are specified, all possible information
is extracted.  Tag names may begin with '-' indicating tags to exclude.  The
tag names are case-insensitive, so note that the returned tags may not be
exactly the same as the requested tags. For this reason it is best to use
either the keys of the returned hash or the elements of the tag array when
accessing the return values

=item GLOB ref

A reference to an open image file.

=item SCALAR ref

A reference to image data in memory.

=item ARRAY ref

Reference to a list of tag names.  On entry, any elements in the list are
added to the list of requested tags.  Tags with names beginning with '-' are
excluded.  On return, this list is updated to contain a sorted list of tag
names in the proper case.

=item HASH ref

Reference to a hash containing the options settings.  See B<Options>
documentation below for a list of available options.  Options specified
as arguments to B<ImageInfo> take precidence over B<Options> settings.

=back

=item Return Values:

B<ImageInfo> returns a reference to a hash of tag/value pairs. The keys of
the hash are the tag identifiers, which are similar to the tag names but my
have an embedded copy number if more than one tag with that name was found
in the image.  Use B<GetTagName> to remove the copy number from the tag.
Note that the case of the tags may not be the same as requested. Here is a
simple example to print out the information returned by B<ImageInfo>:

    foreach (sort keys %$info) {
        print "$_ => $$info{$_}\n";
    }

The values of the returned hash are usually simple scalars, but a scalar
reference is used to indicate binary data.  Note that binary values are not
necessarily extracted unless specifically requested or the Binary option is
set.  If not extracted the value is a reference to a string of the form
"Binary data ##### bytes".  The code below gives an example of how to handle
these return values, as well as illustrating the use of other ExifTool
functions:

    use Image::ExifTool;
    my $exifTool = new Image::ExifTool;
    $exifTool->Options(Unknown => 1);
    my $info = $exifTool->ImageInfo('a.jpg');
    my $group = '';
    my $tag;
    foreach $tag ($exifTool->GetFoundTags('Group0')) {
        if ($group ne $exifTool->GetGroup($tag)) {
            $group = $exifTool->GetGroup($tag);
            print "---- $group ----\n";
        }
        my $val = $info->{$tag};
        if (ref $val eq 'SCALAR') {
            if ($$val =~ /^Binary data/) {
                $val = "($$val)";
            } else {
                my $len = length($$val);
                $val = "(Binary data $len bytes)";
            }
        }
        printf("%-32s : %s\n", $exifTool->GetDescription($tag), $val);
    }

As well as tags representing information extracted from the image,
the following tags generated by ExifTool may be returned:

    ExifToolVersion - The ExifTool version number.

    Error - An error message if the image could not be read.

    Warning - A warning message if problems were encountered
              while extracting information from the image.

=back

=head2 Options

Get/set ExifTool options.  This function can be called to set the default
options for an ExifTool object.  Options set this way are in effect for
all function calls but may be overridden by options passed as arguments
to a specific function.

    # Exclude the 'OwnerName' tag from returned information
    $exifTool->Options( Exclude => 'OwnerName' );

    # Only get information in EXIF or MakerNotes groups
    $exifTool->Options( Group0 => [ 'EXIF', 'MakerNotes' ] );

    # Ignore information from IFD1
    $exifTool->Options( Group1 => '-IFD1' );

    # Sort by groups in family 2, and extract unknown tags
    $exifTool->Options( Sort => 'Group2', Unknown => 1 );

    # Do not extract duplicate tag names
    $oldSetting = $exifTool->Options( Duplicates => 0 );

=over 4

=item Inputs:

0) ExifTool object reference.

1) Option parameter name.

2) [optional] Option parameter value.

3-N) [optional] Additional parameter/value pairs.

=item Option Parameters:

=over 4

=item Binary

Flag to get the value of all binary tags.  Unless set, large
binary values may only be extracted for specifically requested tags.
Default is 0.

=item Composite

Flag to calculate Composite tags automatically.  Default
is 1.

=item DateFormat

Format for printing EXIF date/time.  See L<strftime> for
details about the format string.

=item Duplicates

Flag to preserve values of duplicate tags (instead of
overwriting existing value).  Default is 1.

=item Group#

Extract tags only for specified groups in family # (Group0 assumed if #
not given).  The option value may be a single group name or a reference
to a list of groups.  Case is significant in group names.  Specify a
group to be excluded by preceeding group name with a '-'.  See
B<GetAllGroups> for a list of available groups.

=item Exclude

Exclude specified tags from tags extracted from an image. The
option value is either a tag name or reference to a list of tag names
to exclude.  The case of tag names is not significant. This option is
ignored for specifically requested tags.  Tags may also be excluded
by preceeding their name with a '-' in the arguments to B<ImageInfo>.

=item PrintConv

Flag to enable automatic print conversion.  Default is 1.

=item Sort

Specifies order to sort tags in returned list:

  Alpha  - Sort alphabetically
  File   - Sort in order that tags were found in the file
  Group# - Sort by tag group, where # is the group family
           number.  If # is not specified, Group0 is assumed.
           See GetGroup for a list of groups.
  Input  - Sort in same order as input tag arguments (default)

=item Unknown

Flag to get the values of unknown tags.  If set to 1, unknown tags are
extracted from EXIF directories.  If set to 2, unknown tags are also
extracted from binary data blocks.  Default is 0.

=item Verbose

Flag to print verbose messages.  May be set to a value from 0 to 3 to be
increasingly verbose.  Default is 0.

=back

=item Return Values:

The original value of the last specified parameter.

=back

=head2 ClearOptions

Reset all options to their default values.

    $exifTool->ClearOptions();

=over 4

=item Inputs:

0) ExifTool object reference

=item Return Values:

(none)

=back

=head2 ExtractInfo

Extract meta information from an image.  Call B<GetInfo> to access the
information after extracting it from the image.

    $success = $exifTool->ExtractInfo('image.jpg', \%options);

=over 4

=item Inputs:

B<ExtractInfo> takes exactly the same arguments as B<ImageInfo>.  The only
difference is that a list of tags is not returned if an ARRAY reference is
given.  The following options are effective in the call to B<ExtractInfo>:

Binary, Composite, DateFormat, PrintConv, Unknown and Verbose.

=item Return Value:

1 if image was valid, 0 otherwise (and 'Error' tag set).

=back

=head2 GetInfo

B<GetInfo> is called to return meta information after it has been extracted
from the image by a previous call to B<ExtractInfo> or B<ImageInfo>. This
function may be called repeatedly after a single call to B<ExtractInfo> or
B<ImageInfo>.

    # Get image width and hieght only
    $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');

    # Get information for all tags in list (list updated with tags found)
    $info = $exifTool->GetInfo(\@ioTagList);

    # Get all information in Author or Location groups
    $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});

=over 4

=item Inputs:

Inputs are the same as B<ExtractInfo> and B<ImageInfo> except that an image
can not be specified.  Options in effect are:

Duplicates, Exclude, Group#, (and Sort if tag list reference is given).

=item Return Value:

Reference to information hash, the same as with B<ImageInfo>.

=back

=head2 CombineInfo

Combine information from more than one information hash into a single hash.

    $info = $exifTool->CombineInfo($info1, $info2, $info3);

=over 4

=item Inputs:

0) ExifTool object reference

1-N) Information hash references

=back

If the Duplicates option is disabled and duplicate tags exist, the order of
the hashes is significant.  In this case, the value used is the first value
found as the hashes are scanned in order of input.  The Duplicates option
is the only option that is in effect for this function.

=head2 GetTagList

Get a sorted list of tags from the specified information hash or tag list.

    @tags = $exifTool->GetTagList($info, 'Group0');

=over 4

=item Inputs:

0) ExifTool object reference,

1) [optional] Information hash reference or tag list reference,

2) [optional] Sort order ('File', 'Input', 'Alpha' or 'Group#').

If the information hash or tag list reference is not provided, then the list
of found tags from the last call to B<ImageInfo> or B<GetInfo> is used
instead, and the result is the same as if B<GetFoundTags> was called.  If
sort order is not specified, the sort order from the current options is used.

=item Return Values:

A list of tags in the specified order.

=back

=head2 GetFoundTags

Get list of found tags in specified sort order.  The found tags are the
tags for the information returned from the most recent call to B<ImageInfo>
or B<GetInfo> for this object.

    @tags = $exifTool->GetFoundTags('File');

=over 4

=item Inputs:

0) ExifTool object reference

1) [optional] Sort order ('File', 'Input', 'Alpha' or 'Group#')

If sort order is not specified, the sort order from the ExifTool options is
used.

=item Return Values:

A list of tags in the specified order.

=back

=head2 GetRequestedTags

Get list of requested tags.  These are the tags that were specified in the
arguments of the most recent call to B<ImageInfo>, B<ExtractInfo> or
B<GetInfo>, including tags specified via a tag list reference. Shortcut
tags are expanded in the list.

    @tags = $exifTool->GetRequestedTags();

=over 4

=item Inputs:

(none)

=item Return Values:

List of requested tags in the same order that they were specified.
Note that this list will be empty if tags were not specifically requested
(ie. If extracting all tags).

=back

=head2 GetValue

Get the value of specified tag.  By default this routine returns the
human-readable (PrintConv) value, but optionally returns the
machine-readable (ValueConv) value. Note that the PrintConv value will
only differ from the ValueConv value if the PrintConv option is enabled
(which it is by default).  The PrintConv values are the values returned
by B<ImageInfo> and B<GetInfo> in the tag/value hash.

    $val = $exifTool->GetValue('ISO', 'ValueConv');

=over 4

=item Inputs:

0) ExifTool object reference

1) Tag key

2) [optional] Value type, 'PrintConv' (default) or 'ValueConv'

=item Return Values:

The value of the specified tag.

=back

=head2 GetDescription

Get description for specified tag.  This function will always return a
defined value.  In the case where the description doesn't exist, the tag
name is returned.

=over 4

=item Inputs:

0) ExifTool object reference

1) Tag key

=item Return Values:

A description for the specified tag.

=back

=head2 GetGroup

Get group name for specified tag.

    $group = $exifTool->GetGroup($tag, 0);

=over 4

=item Inputs:

0) ExifTool object reference

1) Tag key

2) [optional] Group family number

=item Return Values:

Group name (or 'Other' if tag has no group).  If no group family is
specified, B<GetGroup> returns the name of the group in family 0 when called
in scalar context, or the names of groups for all families in list context.
See B<GetAllGroups> for a list of groups in each famly.

=back

=head2 GetGroups

Get list of group names for specified information.

    @groups = $exifTool->GetGroups($info, 2);

=over 4

=item Inputs:

0) ExifTool object reference

1) [optional] Info hash ref (default is all extracted info)

2) [optional] Group family number (default 0)

=item Return Values:

List of group names in alphabetical order. If information hash is not
specified, the group names are returned for all extracted information.

=back

=head2 BuildCompositeTags

Builds composite tags from required tags.  The composite tags are
convenience tags which are derived from the values of other tags.  This
routine is called automatically by B<ImageInfo> and B<ExtractInfo> if the
Composite option is set.

=over 4

=item Inputs:

0) ExifTool object reference

=item Return Values:

(none)

=item Notes:

Tag values are calculated in alphabetical order unless a tag Require's or
Desire's another composite tag, in which case the calculation is deferred
until after the other tag is calculated. Composite tags may need to read
data from the image for their value to be determined, so for these
B<BuildCompositeTags> must be called while the image is available.  This is
only a problem if B<ImageInfo> is called with a filename (as opposed to a
file reference or scalar reference) since in this case the file is closed
before B<ImageInfo> returns.  However if you enable the Composite
option, B<BuildCompositeTags>  is called from within B<ImageInfo> before the
file is closed.  (Note: As of ExifTool version 3.10, only the PreviewImage
required access to the image data.)

=back

=head2 GetTagName [static]

Get name of tag from tag key.  This is a convenience function that
strips the embedded copy number, if it exists, from the tag key.

Note: "static" in the heading above indicates that the function does not
require an ExifTool object reference as the first argument.  All functions
documented below are also static.

    $tagName = Image::ExifTool::GetTagName($tag);

=over 4

=item Inputs:

0) Tag key

=item Return Value:

Tag name.  This is the same as the tag key but has the copy number removed.

=back

=head2 GetShortcuts [static]

Get a list of shortcut tags.

=over 4

=item Inputs:

(none)

=item Return Values:

List of shortcut tags (as defined in Image::ExifTool::Shortcuts).

=back

=head2 GetAllTags [static]

Get list of all available tag names.

    @tagList = Image::ExifTool::GetAllTags();

=over 4

=item Inputs:

(none)

=item Return Values:

A list of all available tags in alphabetical order.

=back

=head2 GetAllGroups [static]

Get list of all group names in specified family.

    @groupList = Image::ExifTool::GetAllGroups($family);

=over 4

=item Inputs:

0) Group family number (0-2)

=item Return Values:

A list of all groups in the specified family in alphabetical order.

=back

Three families of groups are currently defined: 0, 1 and 2. Families 0 and 1
are based on the file structure, and family 2 classifies information based
on the logical category to which the information refers.

Families 0 and 1 are similar except that family 1 is more specific, and
sub-divides the EXIF, MakerNotes and XMP groups to give more detail about
the specific location where the information was found.  The EXIF group is
split up based on the specific IFD (Image File Directory), the MakerNotes
group is divided into groups for each manufacturer, and the XMP group is
separated based on the XMP namespace prefix.  Note that only common XMP
namespaces are listed below but additional namespaces may be present in some
XMP data.  Also note that the 'XMP-xmp...' group names may appear in the
older form 'XMP-xap...' since these names evolved as the XMP standard
was developed.

Here is a complete list of groups for each family:

=over 4

=item Family 0 (General Location):

Composite, EXIF, ExifTool, File, GPS, GeoTiff, IPTC, MakerNotes, Photoshop,
PrintIM, XMP

=item Family 1 (Detailed Location):

Canon, CanonCustom, CanonRaw, Casio, Composite, ExifIFD, ExifTool, File,
FujiFilm, GlobParamIFD, GPS, GeoTiff, IFD0, IFD1, IPTC, InteropIFD,
MakerUnknown, Minolta, Nikon, Olympus, Pentax, Photoshop, PrintIM, Sanyo,
Sigma, Sony, SubIFD, XMP-aux, XMP-crs, XMP-dc, XMP-exif, XMP-photoshop,
XMP-tiff, XMP-xmp, XMP-xmpBJ, XMP-xmpMM, XMP-xmpRights

=item Family 2 (Category):

Author, Camera, ExifTool, Image, Location, Other, Printing, Time, Unknown

=back

=head1 AUTHOR

Copyright 2003-2004, Phil Harvey (phil@owl.phy.queensu.ca)

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 CREDITS

Thanks to the following people for their help:

B<Malcolm Wotton> for his help with the D30 Custom Functions.

B<David Anson> for his help sorting out binary file problems on Windows.

B<Leon Booyens> for his suggestions.

B<Jeremy Brown> for the 35efl tags.

B<Dan Heller> for his bug reports, detailed suggestions and guidance.

B<Wayne Smith> for his help figuring out the Pentax maker notes.

B<Michael Rommel> for his bug fixes and additions to the Canon maker notes.

B<Joseph Heled> for help figuring out some of the Nikon D70 maker notes.

B<Joachim Loehr> for adding the Casio type 2 maker notes.

B<Greg Troxel> for his suggestions and for adding ExifTool to pkgsrc-wip.

=head1 SEE ALSO

L<Image::Info|Image::Info> L<Image::MetaData::JPG|Image::MetaData::JPG>

=cut

# end
