Image::Shoehorn - massage the dimensions and filetype of an image

 use Image::Shoehorn;
 use Data::Dumper;

 my $image = Image::Shoehorn->new({
                                   tmpdir     => "/usr/tmp",
                                   cleanup    => \&my_cleanup
                                  }) || die Image::Shoehorn->last_error();

 my $imgs = $image->import({
                            source     => "/some/large/image.jpg",
                            max_height => 600,
                            valid      => [ "png" ],
                            convert    => 1,
                            scale      => { thumb => "x50", small => "50%" },
                            overwrite  => 1,
                           }) || die Image::Shoehorn->last_error();

 print &Dumper($imgs);

Image::Shoehorn will massage the dimensions and filetype of an image, optionally creating one or more "scaled" copies.

It uses Image::Magick to do the heavy lifting and provides a single "import" objet method to hide a number of tasks from the user.

Just before I decided to submit this package to the CPAN, I noticed that Lee Goddard had just released Image::Magick::Thumbnail. Although there is a certain amount of overlap, creating thumbnails is only a part of the functionality of Image::Shoehorn.

Image::Shoehorn is designed for taking a single image, optionally converting its file type and resizing it, and then creating one or more "scaled" versions of the (modified) image.

One example would be a photo-gallery application where the gallery may define (n) number of scaled versions. In a mod_perl context, if the scaled image had not already been created, the application might create the requested image for the request and then register a cleanup handler to create the remaining "scaled" versions. Additionally, scaled images may be defined as "25%", "x50", "200x" or "25x75" (Apache::Image::Shoehorn is next...)

This package started life as Image::Import; designed to slurp and munge images into a database. It's not a very exciting name and, further, is a bit ambiguous.

So, I started fishing around for a better name and for a while I was thinking about Image::Tailor - a module for taking in the "hem" of an image, of fussing and making an image fit properly.

When I asked the Dict servers for a definition of "tailor", it returned a WordNet entry containing the definition...

 make fit for a specific purpose [syn: {shoehorn}]

..and that was that.

Returns the last error recorded by the object.

Object constructor. Valid arguments are :

• tmpdir
  
  String.
  
  The path to a directory where your program has permissions to create new files. Required
• cleanup
  
  Code reference.
  
  By default, any new images that are created, in the tmp directory, are deleted when a different image is imported or when the Image::Shoehorn::DESTROY method is invoked.
  
  You may optionally provide your own cleanup method which will be called in place.
  
  Your method will be passed a hash reference where the keys are "source" and any other names you may define in the scale parameter of the import object method. Each key points to a hash reference whose keys are :
• • path
  • width
  • height
  • format
  • type


Note that this method will only affect new images. The original source file may be altered, if it is imported with the overwrite parameter, but will not be deleted.

Returns an object. Woot!

Valid arguments are :

• source
  
  String.
  
  The path to the image you are trying to import. If ImageMagick can read it, you can import it.
  
  Required
• max_width
  
  Int.
  
  The maximum width that the image you are importing may be. Height is scaled accordingly.
• max_height
  
  Int.
  
  The maximum height that the image you are importing may be. Width is scaled accordingly.
• scale
  
  Hash reference.
  
  One or more key-value pairs that define scaling dimensions for creating multiple instances of the current image.
  
  The key is a human readable label because humans are simple that way. The key may be anything you'd like except "source" which is reserved for the image the object is munging.
  
  The value for a given key is the dimension flag which may be represented as :
• • n%
  • nxn
  • xn
  • nx


Note that images are scaled after the original source file may have been resized according to the max_height, max_width flags and convert flags.

Scaled images are created in the tmp_dir defined in the object constructor.
• valid
  
  Array reference.
  
  An list of valid file-types for which Image::Magick has encoding support.
• convert
  
  Boolean.
  
  If this value is true and the source does not a valid file-type, the method will create a temporary file attempt to convert it to one of the specified valid file-types. The method will try to convert in the order the valid file-types are specified, stopping on success.
• cleanup
  
  Code reference.
  
  Define a per instance cleanup function for an image. This functions exactly the same way that a cleanup function defined in the object constructor does, except that it is forgotten as soon as a new image is imported.
• overwrite
  
  Boolean.
  
  Indicates whether or not to preserve the source file. By default, the package will not perform munging on the source file itself and will instead create a new file in the tmp_dir defined in the object constructor.

Returns a hash reference with information for the source image -- note that this may or may not be the input document, but the newly converted/resized image created in you tmp directory -- and any scaled images you may have defined.

The keys of the hash are human readable names. The values are hash references whose keys are :

• path
• height
• width
• extension
• contenttype
• format
• type
  
  Deprecated in favour or extension

If there was an error, the method will return undef.

1.42

$Date: 2003/05/30 22:51:06 $

Aaron Straup Cope

• Modify constructor to accept all the options defined in the import method as defaults.
• Modify import to accept multiple files.
• Modify import to accept strings and filehandles.

Image::Magick

Image::Magick::Thumbnail

Copyright (c) 2001-2003, Aaron Straup Cope. All Rights Reserved.

This is free software, you may use it and distribute it under the same terms as Perl itself.