Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IPTCInfo(3)	      User Contributed Perl Documentation	   IPTCInfo(3)

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).

perl v5.32.0			  2007-11-08			   IPTCInfo(3)

NAME | SYNOPSIS | DESCRIPTION | USING IPTCINFO | IPTC ATTRIBUTE REFERENCE | KNOWN BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Image::IPTCInfo&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help