Josh Carter > Image-IPTCInfo > Image::IPTCInfo

Download:
Image-IPTCInfo-1.95.tar.gz

Dependencies

Annotate this POD

Related Modules

Image::Magick
File::Slurp
more...
By perlmonks.org

CPAN RT

New  5
Open  0
View/Report Bugs
Module Version: 1.95   Source  

NAME ^

Image::IPTCInfo - Perl extension for extracting IPTC image meta-data

SYNOPSIS ^

  use Image::IPTCInfo;

  # Create new info object
  my $info = new Image::IPTCInfo('file-name-here.jpg');

  # Check if file had IPTC data
  unless (defined($info)) { die Image::IPTCInfo::Error(); }
    
  # Get list of keywords, supplemental categories, or contacts
  my $keywordsRef = $info->Keywords();
  my $suppCatsRef = $info->SupplementalCategories();
  my $contactsRef = $info->Contacts();
    
  # Get specific attributes...
  my $caption = $info->Attribute('caption/abstract');
    
  # Create object for file that may or may not have IPTC data.
  $info = create Image::IPTCInfo('file-name-here.jpg');
    
  # Add/change an attribute
  $info->SetAttribute('caption/abstract', 'Witty caption here');

  # Save new info to file 
  ##### See disclaimer in 'SAVING FILES' section #####
  $info->Save();
  $info->SaveAs('new-file-name.jpg');

DESCRIPTION ^

Ever wish you add information to your photos like a caption, the place you took it, the date, and perhaps even keywords and categories? You already can. The International Press Telecommunications Council (IPTC) defines a format for exchanging meta-information in news content, and that includes photographs. You can embed all kinds of information in your images. The trick is putting it to use.

That's where this IPTCInfo Perl module comes into play. You can embed information using many programs, including Adobe Photoshop, and IPTCInfo will let your web server -- and other automated server programs -- pull it back out. You can use the information directly in Perl programs, export it to XML, or even export SQL statements ready to be fed into a database.

USING IPTCINFO ^

Install the module as documented in the README file. You can try out the demo program called "demo.pl" which extracts info from the images in the "demo-images" directory.

To integrate with your own code, simply do something like what's in the synopsys above.

The complete list of possible attributes is given below. These are as specified in the IPTC IIM standard, version 4. Keywords and categories are handled differently: since these are lists, the module allows you to access them as Perl lists. Call Keywords() and Categories() to get a reference to each list.

NEW VS. CREATE

You can either create an object using new() or create():

  $info = new Image::IPTCInfo('file-name-here.jpg');
  $info = create Image::IPTCInfo('file-name-here.jpg');

new() will create a new object only if the file had IPTC data in it. It will return undef otherwise, and you can check Error() to see what the reason was. Using create(), on the other hand, always returns a new IPTCInfo object if there was data or not. If there wasn't any IPTC info there, calling Attribute() on anything will just return undef; i.e. the info object will be more-or-less empty.

If you're only reading IPTC data, call new(). If you want to add or change info, call create(). Even if there's no useful stuff in the info object, you can then start adding attributes and save the file. That brings us to the next topic....

MODIFYING IPTC DATA

You can modify IPTC data in JPEG files and save the file back to disk. Here are the commands for doing so:

  # Set a given attribute
  $info->SetAttribute('iptc attribute here', 'new value here');

  # Clear the keywords or supp. categories list
  $info->ClearKeywords();
  $info->ClearSupplementalCategories();
  $info->ClearContacts();

  # Add keywords or supp. categories
  $info->AddKeyword('frob');

  # You can also add a list reference
  $info->AddKeyword(['frob', 'nob', 'widget']);

SAVING FILES

With JPEG files you can add/change attributes, add keywords, etc., and then call:

  $info->Save();
  $info->SaveAs('new-file-name.jpg');

This will save the file with the updated IPTC info. Please only run this on *copies* of your images -- not your precious originals! -- because I'm not liable for any corruption of your images. (If you read software license agreements, nobody else is liable, either. Make backups of your originals!)

If you're into image wizardry, there are a couple handy options you can use on saving. One feature is to trash the Adobe block of data, which contains IPTC info, color settings, Photoshop print settings, and stuff like that. The other is to trash all application blocks, including stuff like EXIF and FlashPix data. This can be handy for reducing file sizes. The options are passed as a hashref to Save() and SaveAs(), e.g.:

  $info->Save({'discardAdobeParts' => 'on'});
  $info->SaveAs('new-file-name.jpg', {'discardAppParts' => 'on'});

Note that if there was IPTC info in the image, or you added some yourself, the new image will have an Adobe part with only the IPTC information.

XML AND SQL EXPORT FEATURES

IPTCInfo also allows you to easily generate XML and SQL from the image metadata. For XML, call:

  $xml = $info->ExportXML('entity-name', \%extra-data,
                          'optional output file name');

This returns XML containing all image metadata. Attribute names are translated into XML tags, making adjustments to spaces and slashes for compatibility. (Spaces become underbars, slashes become dashes.) You provide an entity name; all data will be contained within this entity. You can optionally provides a reference to a hash of extra data. This will get put into the XML, too. (Example: you may want to put info on the image's location into the XML.) Keys must be valid XML tag names. You can also provide a filename, and the XML will be dumped into there. See the "demo.pl" script for examples.

For SQL, it goes like this:

  my %mappings = (
       'IPTC dataset name here' => 'your table column name here',
       'caption/abstract'       => 'caption',
       'city'                   => 'city',
       'province/state'         => 'state); # etc etc etc.
    
  $statement = $info->ExportSQL('mytable', \%mappings, \%extra-data);

This returns a SQL statement to insert into your given table name a set of values from the image. You pass in a reference to a hash which maps IPTC dataset names into column names for the database table. As with XML export, you can also provide extra information to be stuck into the SQL.

IPTC ATTRIBUTE REFERENCE ^

  object name               originating program
  edit status               program version
  editorial update          object cycle
  urgency                   by-line
  subject reference         by-line title
  category                  city
  fixture identifier        sub-location
  content location code     province/state
  content location name     country/primary location code
  release date              country/primary location name
  release time              original transmission reference
  expiration date           headline
  expiration time           credit
  special instructions      source
  action advised            copyright notice
  reference service         contact
  reference date            caption/abstract
  reference number          local caption
  date created              writer/editor
  time created              image type
  digital creation date     image orientation
  digital creation time     language identifier

  custom1 - custom20: NOT STANDARD but used by Fotostation.
  IPTCInfo also supports these fields.

KNOWN BUGS ^

IPTC meta-info on MacOS may be stored in the resource fork instead of the data fork. This program will currently not scan the resource fork.

I have heard that some programs will embed IPTC info at the end of the file instead of the beginning. The module will currently only look near the front of the file. If you have a file with IPTC data that IPTCInfo can't find, please contact me! I would like to ensure IPTCInfo works with everyone's files.

AUTHOR ^

Josh Carter, josh@multipart-mixed.com

SEE ALSO ^

perl(1).

syntax highlighting: